Web API checklist: 43 things to consider when designing, testing, and releasing APIs

When designing, testing, or releasing a new web API, you build a new system on an original complex system. At least, you should also build on HTTP, while HTTP is based on TCP/IP, and TCP/IP is built on a series of pipelines. Of course, you also need to consider web servers and ApplicationsProgramFramework or API framework.

It takes a long process to design, test, and final release an API. This article will focus on things that developers may ignore or pay attention to from the design to the final release of a web API.

HTTP

The HTTP 1.1 Standard rfc2616 is a very large document. Here we extract some content that may affect the API and share it with you:

1. idempotent Methods: Get, head, put, delete, options, and trace all belong to the idempotent operation. That is to say, "The side-effects of N> 0 identical requests is the same as for a single request. "(rfc2616 § 9. 1.2)

2. Verification: The Authorization header file provided by HTTP is for this purpose (Rfc2616 § 14. 8). Rfc2617 specifies a specific verification plan, including the most common basic HTTP verification.

3.201 created: Use "201 created" for responseCodeThe request is successful and a new resource is created. 201 the response can contain the new resource URI in the local header file. (Rfc2616 § 10. 2.2)

4.202 accepted: using the "202 accepted" response code indicates that the request is valid and will be processed, but it has not been completed yet. Generally, it is used in the background queue of the server. (Rfc2616 § 10. 2.3)

Status Code 5.4xx and 5xx: the status code 4xx has a very important difference with the status code 5xx: The 4xx Code is designed to indicate client errors, while the 5xx code indicates server errors. (Rfc2616 § 62.1.1)

6.410 gone: the "410 gone" response code is a rarely used response code. It mainly notifies the client that the resource appears in the URL, but it does not. This API can be used to specify the items to be deleted, archived, or expired. (Rfc2616 § 10. 4.11)

7. keep CT: 100-continue: If the API client intends to send a large object request, such as post, put, or patch, it can send "Keep CT: 100-continue" to the HTTP header file, wait for the "100 continue" response before sending the entity. This allows the API to verify reasonable requests (such as 401 or 403) before returning error response information ). Using it can improve API response capabilities and reduce bandwidth in some scenarios. (Rfc2616 § 8. 2.3)

8. Smooth connection: It can be connected to the API server, which greatly improves the performance of multiple API requests. If the configuration is correct, each web server should support the keep-alive connection.

9. Http compression: HTTP compression can be used for both the response body (accept-encoding: gzip) and request body (content-encoding: gzip) to improve the network performance of HTTP APIs.

10. Http cache: A cache-control header file is provided when the API responds. (Rfc2616 § 14. 9)

11. cache verification: If you have a cache API, you should provide the last-modified or etag header file in response, the IF-modified-since or if-None-match header files are supported for conditional requests. This will allow the client to check whether their cached copies are still valid and prevent a full download of resources when no request is sent. If implemented properly, conditional requests are more effective than normal requests. (Rfc2616 § 13. 3)

12. Condition modification: The etag header file can also be used to modify resources with conditions. (Rfc2616 § 14. 24)

13. Absolute redirection: This is a little-known HTTP/1.1 requirement, redirection (for example. 201, 301, 302, 303, 307 response code) should contain an absolute URI local response header file. Many clients support relative Uris locally, but if you want to make the API compatible with more clients, you should use absolute Uris during redirection. (Rfc2616 § 14. 30)

14. Link response header file: in restful APIs, you often need to provide links to other resources. Even the response content type cannot provide a natural link (such as PDF or image ). Rfc5988 specifies a link provision method in the response header file.

15. Standard URL: For multi-resource URLs, rfc6596 defines a unified method to regulate URL links.

16. block Transfer Encoding: If the response content is too large, the Transfer Encoding: chunked is a good way to stream the response to the client, it reduces the memory usage requirements of servers and intermediate servers (especially for HTTP compression) and provides faster first byte response.

17. Block Transfer Encoding Error Handling: before implementing block transfer encoding, it is very important to find out how to handle errors generated when an intermediate request occurs. Once the response is streamed, the HTTP Status Code cannot be changed.

18. x-http-method-override: some HTTP clients do not support any get or post operations, but you can activate other HTTP methods through post, use the standard X-http-method-overrider header file to define the "true" HTTP method.

19. URL Length: If the API supports complex or arbitrary filtering items as get parameters, remember that compatibility issues may occur between the client and the server because the URL length exceeds 2000 bytes.

API design

20. Stateless: no one wants the API to store status, even on your application server. Keep the application server in a free state and make it easy and easy to scale.

21. content negotiation: allows your resources to support multiple expressions. You can use content negotiation (content negotiation, such as the accept header file) or use different URLs (such ......? Format = JSON), or you can redirect your content negotiation to a specific format.

22. Uri template: a URI template is a well-defined mechanism that provides URI combination capabilities to the client, or defines the URL access terminal user mode.

23. Design for intent: do not expose internal business objects only through APIS. Designing API semantics means matching with user cases. For a better introduction, you can read the API craft written by Darrel Miller.

24. Version: theoretically, a well-designed API does not need to be compatible. For utilities, they put the version into the api url (for example, A/V1/path). Therefore, unless it is in a secure network, otherwise, the API may not work as expected.

25. Authorization: Remember, when designing an API, not all users can access any objects in it.

26. batch operation: Send fewer requests to obtain or modify more data. The best way is to use batch operation in your API.

27. Mark pages: the API uses paging service for two main purposes: one is to reduce unnecessary data transmitted to the client; the other is to reduce unnecessary operations on the application server.

28. unified character encoding: when designing and testing APIs, Web services must support more English characters. If you use Unicode bytes as the natural key in the URL, it will be very interesting (for example,/users/jimbob/becomes/users/character keys /).

29. Error Log: it is also important to create an error log when designing an API. In practice, it is best to create two types of logging: server and client.

Content

30. content type: content type can be used to write a whole book. Personally, I prefer to reuse the content type developed by others, like atom, collection + JSON, JSON Hal, or XHTML. Defining a set of content types is better than you expected.

31. hateoas: As the application state engine, hypermedia is a restful constraint. Simply put, your content should notify the client of what to do and can be notified through links or forms.

32. date/time: When you provide the date/time value in the API, you should use a format, including time zone information. Rfc3339 is a subset of iso8601 and is the simplest date and time format.

Security

33. SSL: whether or not your API supports HTTP or HTTPS, you should consider the HTTPS access method, and its growth trend is becoming increasingly obvious.

34. Cross-Site Request Forgery (csrf): If the interactive users using APIs use the same authentication as normal users, your API may be vulnerable to csrf attacks.

35. throttling: If the number of requests of an API user exceeds the limit, you should provide a 503 response with retry-after header.

36. Declined Denial-of-Service (DoS): throttling can prevent you from launching attacks in the simplest way, but there are other more witty attacks here. For example, Slowloris, billion laughs, and redos do not occupy too many resources, but they can make your API consume all resources instantly.

Client

Whether you provide users with test code or SDK, you should provide them with a client and follow these steps:

37. Keep the connection smooth: some HTTP clients need to do some extra work to keep the connection persistent. Persistent connections have a very important impact on API performance perception.

38. Another quirks of HTTP before authorization is that they send a "401 unauthorized" response before resolving an authorization issue. This will prolong the API request time.

39. keep CT: 100-continue: at least one API client uses "Keep CT: 100-continue" by default. If it does not accept the "100 continue" response, the request will continue to be sent after 3 seconds of timeout. If the API does not support "100 continue", another performance defect may occur, causing the client to be disabled.

Others

40. Documentation: Writing API documentation is boring, but hand-written API documentation is usually the best. You must include the following content when writing: Some executable code or curl command lines for easy reference. You can also refer to some document tools, such as apiary. Io, mashery I/O docs, and swagger.

41. Design and Customer: Do not design APIs in a vacuum environment. You must deal with or design APIs together. Refer to user cases.

42. Feedback: a channel should be provided for users to provide feedback during API design,

43. Automated Testing: API testing is the simplest thing. It is better to be automated. After all, you need to make good use of it.

Is the list provided above interesting? Is it helpful to you? Welcome to discuss with us.

From: Mathieu fenniak