13/10/2024
๐ช๐ต๐ฎ๐ ๐ฎ๐ฟ๐ฒ ๐๐ฃ๐ ๐๐ป๐๐ถ-๐ฃ๐ฎ๐๐๐ฒ๐ฟ๐ป๐?
There are design patterns in software design, which are good practices, but we also have anti-patterns. These anti-patterns often seem like good ideas initially but can lead to different problems over time.
This holds not only for general software design but also in the API world.
Here are some common API anti-patterns we can see in the wild:
๐ญ. ๐จ๐๐ถ๐ป๐ด ๐๐ฟ๐ผ๐ป๐ด ๐๐ง๐ง๐ฃ ๐บ๐ฒ๐๐ต๐ผ๐ฑ๐
If we don't align with RESTful design principles, this can lead to a confusing and unpredictable API.
Here are some examples of such problems:
๐น Using POST instead of appropriate GET, PUT, and DELETE methods for all operations. For example: Using POST /updateUser instead of PUT /users/{id}
๐น Focusing on actions rather than resources. For example, GET /getLatestCheckout instead of GET /checkout
๐ฎ. ๐จ๐ฅ๐ ๐ถ๐ ๐ป๐ผ๐ ๐ฅ๐๐ฆ๐ง๐ณ๐๐น
There could be multiple issues in this area:
๐น Switching between singular and plural resource names, for example
/user/{id} for a single user, but /companies for multiple companies
๐น Mixing action verbs and nouns in endpoint names, for example: /createPost vs /comments
๐ฏ. ๐๐ฎ๐ฑ ๐๐ฟ๐ฟ๐ผ๐ฟ ๐๐ฎ๐ป๐ฑ๐น๐ถ๐ป๐ด
An example could be generic error messages, such as always returning "An error occurred" instead of "Invalid email format."
Another example is using incorrect or non-standard status codes, such as Returning 200 OK for all responses, even when an error occurs. We need to know some major response status codes, but we can also create our own.
๐ฐ. ๐๐ด๐ป๐ผ๐ฟ๐ถ๐ป๐ด ๐ฐ๐ฎ๐ฐ๐ต๐ถ๐ป๐ด
We usually don't use any caching mechanism with our REST APIs, even though we have many options. This can degrade application performance.
For example, we can use HTTP caching headers like ETag, Cache-Control, and Last-Modified to control how responses are cached by clients, which will increase application stability and performance.
๐ฑ. ๐ ๐ถ๐๐๐ถ๐ป๐ด ๐๐ฃ๐ ๐ฑ๐ผ๐ฐ๐๐บ๐ฒ๐ป๐๐ฎ๐๐ถ๐ผ๐ป
Proper documentation can help us understand how to interact with our APIs. We want to invest time in creating proper documentation covering all API aspects, including endpoints, parameters, data models, error codes, and examples of typical requests and responses. We can use tools like Swagger (OpenAPI Specification) to generate interactive documentation.