Co-Founder Taliferro
Introduction
If you're not an API developer, this might seem like a boring subject to read about. But it's essential. An API is how other people interact with your product or service, so it must be well-designed and easy to use. In this post, I'll look at some best practices for writing APIs, and they can apply to any language or framework.
easy-to-read
As APIs have grown, JSON is the most common data format used to exchange data between clients and servers. This is because it's simple and readable by humans, making debugging problems with an API easy. In addition, since JSON is a subset of JavaScript, many web applications can quickly parse this format without making additional code changes (almost all modern browsers support JavaScript).
Keep it consistent
Consistency in your code is essential for usability, maintainability, and readability. But it's also a crucial aspect of security.
For instance, if you use the same variable name for something different in two different places (e.g., "user_id" as a string vs. an integer), depending on how you use it (e.g., printing out the value or passing it to another function) you'll end up with an error that might be hard to find because there are many places where the variable is referenced. This adds extra time and effort for debugging, complicating things when something goes wrong in user-facing software like websites or mobile apps.
On top of this issue, if your application relies on external services (e.g., social media accounts), any inconsistencies between those services could cause problems if not handled properly and lead to inaccurate data being stored within a system.
Return the correct status codes
When returning a response, be sure to use the correct status code. This helps your API clients understand what happened and what they should do next.
You should return a 200 OK when your request is successful but it may take some time to complete. For example, when sending an email through SendGrid, you'll receive a 200 OK if the recipient has been added successfully, but it could take up to five minutes for that message to arrive in their inbox.
You can also use 4xx and 5xx status codes for errors such as invalid parameters or internal server issues (e.g., 500 Internal Server Error).
Proportion
The most critical aspect of API code is how easy it is to read and how difficult it is to make changes. API code should be easy to read and understand. If your code has too much logic, this can confuse developers who need to become more familiar with what's going on under the hood of your app. Conversely, suppose there's too little logic in an API function that would typically require some thought or understanding on the developer's behalf. In that case, they might not fully understand what they're doing when trying to implement that function into their app — and therefore end up breaking something else inadvertently as a result. The primary audience for your API is other developers who will be using it in their apps, so you want them to have a good idea of what your API does just by looking at it.
The easiest way around these problems is simply keeping all business logic out of the actual server side implementation itself; instead put all business rules into separate classes/functions which can easily be tested separately from each other as well as being reused across different APIs without having any negative impact on functionality or performance due out there.
Don't get cute - stick with CRUD
When designing a new API, you should avoid getting cute. Don't try to be clever or innovative regarding the basic structure of your API. Start with CRUD (Create, Read, Update and Delete) as the basis for your API and stick with it.
You might be tempted to create an interface that looks different than other APIs you've seen, something more relational or graph-like. It could be something that doesn't fit into any category of existing APIs. I can tell you from experience that this will only cause problems for everyone involved in building out your system. You are better off sticking with standard conventions until they become familiar enough that people don't need them explained anymore.
Don't put verbs in your API name.
Use nouns.
Don't put unnecessary words in the URL pattern. Use resource restrictive URLs, meaning every level in the URL leads to a data element or collection.
Leave out attributes that aren't needed for POST, PUT and PATCH operations.
When designing your API, it's essential to leave out attributes that aren't needed for POST, PUT and PATCH operations. The only HTTP verbs that modify the resource are POST (create), PUT (update), and DELETE.
It's good practice to use idempotent methods because when a request succeeds multiple times in a row, it doesn't change anything. This behavior is useful when dealing with lists because there isn't necessarily any order of operations, so if a user makes multiple attempts at adding an item within the same request, then we can assume that they don't care about doing so in any particular order.
Conclusion
These are just a few of the API design best practices I've learned over the years.
Tyrone Showers