• Is Your REST API Ready for Deployment? 7 Questions to Help You Decide
  • Originally written by Zac Johnson
  • The Nuggets translation Project
  • Permanent link to this article: github.com/xitu/gold-m…
  • Translator: Renzi Meng
  • Proofreader: Roc

Building an API can seem daunting, and for good reason. A lot of things can go wrong. Rather than start from scratch after your REST API is already deployed, it’s better to carefully build a good API from the start.

How do you know when to say “Wait… don’t deploy this API yet”?

The following questions can help you determine the answer.

Do you document your REST API effectively?

Frankly, if your API provides poor (or no) documentation, developers won’t want to use it. Design your documentation to guide developers through the important aspects of the API and make it easy to use. Your documentation should also make it easy for developers to maintain and update the API.

Creating a tutorial:

  • Publicly accessible
  • Provides a glossary that defines terms
  • Specify and define resources
  • Explain your API methods

If you don’t know where to start, tools like Raml or Swagger can help.

Does your REST API use the right data format?

When designing an API, you can choose the data format, and the format you choose can make or break the difference. Because the API is the connection point between the client and server, its data format needs to be user-friendly for both sides.

Popular formats include:

  • Direct formats (such as JSON, XML, YAML). These formats are used to manage data that is used directly with other systems. They are great for interacting with other APIs.
  • Feed formats (such as RSS, SUP, Atom). These formats are primarily used to serialize social media and blog updates.
  • Database format, such as SQL or CSV. They are ideal for database-to-database and database-to-user communication.

** Are you naming REST API paths efficiently?

** Paths identify the location of resources and specify how to access them.

You should follow good REST practices for naming your paths, including:

  • Simple resource name. Don’t make developers guess resource names, and don’t force them to go through the documentation to find out how to find resources. Make sure the names are intuitive from the start.
  • Use nouns in URIs. RESTful URIs should include a noun (such as “/photos”), not a verb. For example, don’t use names like “/createPhotos”. Do not use any CRUD (Add, delete, change, look) conventions here.
  • Keep the resource name plural. For consistency, use “/photos” or “/ Settings “(instead of “/photo”).
  • Use hyphens, not underscores. Some browsers hide underscores (_). The hyphen (-) is easier to see.
  • Lowercase letters.URI elements are case sensitive (schema (scheme) and host components). For consistency, stick to lowercase letters.

Have you versioned the REST API correctly?

Your API will change over time, so you need to manage those changes. Keep your old API versions active and maintain them for users who still use them.

Proper versioning helps to minimize the number of invalid requests sent to newly updated paths.

Methods of version control include:

  • Add the version number as an attribute in the custom request header
  • Versioning using request parameters, that is, adding a version number as a query parameter
  • Include the current version number in the URI
  • Media type versioning, or changing the Accept header to reflect the current version

Did you test the REST API?

Traditionally, testing has been done on the user interface side, focusing on aspects such as the user experience of the site.

But because the API connects the data layer to the UI, API testing is now considered a critical task. By testing your REST API, you can ensure its performance and functionality.

The types of API tests include:

  • Performance testing. As the name suggests, this gives you a clear idea of the API’s performance. Performance testing includes functional testing and load testing.
  • Unit testing. The unit can be a path, HTTP method (GET, POST, PUT, DELETE), request header or request body.
  • Integration testing. This is probably the most common type of API testing. Your API is at the heart of integrating data, applications, and user devices. Therefore, testing this integration is critical.
  • End to end testing. This type of testing allows you to confirm the smoothness of the data flow between API connections.

Have you established security measures for your REST API?

In the 2020s, hackers are getting smarter and more powerful. You must be vigilant.

Good safety practices include:

  • Use only HTTPS. Secure credentials, such as passwords, JSON Web tokens, API keys, and so on, using ONLY HTTPS. In addition, you should include a timestamp for the HTTP request. This allows the server to accept requests only within a specified time frame to prevent a hacker from attempting a replay attack.
  • Restrict the HTTP methods allowed. Reject all requests that are not in your list of allowed methods.
  • Do not allow sensitive information to be displayed in the URL. Believe it or not, this sometimes happens. Ensure that passwords, usernames, API keys, and so on do not appear in any URL.
  • Security check. Be thorough, don’t take risks. Protect your HTTP cookies and databases. Hide all sensitive data that might be aggregated into the log. Use valid secure password checks and use CSRF tokens.

Have you designed a scalable REST API?

Over time, you need to use the API to handle more and more requests. It is important to design the API to be scalable to maintain its performance and add new functionality as needed.

Estimate the load on the system even before design. Estimate the approximate number of requests per second and request size. Then, check the LOAD distribution, response time, and other important metrics of the API frequently while it is up and running.

Consider using cloud services that automatically scale your system. That way, you don’t have to buy expensive equipment to process more and more data.

Are you ready to run?

Taking the time and paying attention to detail will save you from future setbacks. At each stage of the process, ask yourself, “If I were a developer using this API, would I be happy with it?”

If there are errors or rough patches, there is a reason to pause the deployment to make sure everything is working.

If you find any mistakes in your translation or other areas that need to be improved, you are welcome to the Nuggets Translation Program to revise and PR your translation, and you can also get the corresponding reward points. The permanent link to this article at the beginning of this article is the MarkDown link to this article on GitHub.

The Nuggets Translation Project is a community that translates quality Internet technical articles from English sharing articles on nuggets. The content covers Android, iOS, front-end, back-end, blockchain, products, design, artificial intelligence and other fields. If you want to see more high-quality translation, please continue to pay attention to the Translation plan of Digging Gold, the official Weibo, Zhihu column.