As a developer, you should be familiar with the concept of Application Programming Interface (API). An API is a set of rules and specifications that software programs can follow to communicate with each other. In other words, it is a collection of functions and procedures that let you manipulate data or interact with an external service from your program or a set of requirements that allows one piece of software to interact with another. It serves as an intermediary between different applications, which makes it possible for them to interact with each other.
Designing a Good API
A good API design makes it easier to develop a program by providing all the building blocks, which are then used (consumed) by other programmers. This allows developers to quickly build new products and services by providing access to data and processes that already exist instead of having to code them from scratch.
There are certain features to take into consideration when designing your API, these best practices include:
Remove Ambiguity
The ISO 8601 is the international standard used to represent dates and times. For times, we express them with the notation hours-minutes-seconds, for example, "13:45:28", and for dates, the format is year-month-day, for example, "2015-08-28".
Since 2015, the ISO 8601 timestamp is very commonly used in software development, as it reduces the risk of time-related errors. The value follows the year, month, day, and time in the hour:minute:second:millisecond format. The letter “Z” is generally used as the UTC offset value. And this comes in handy when multiple developers are accessing data from different countries (and time zones), creating the data with this format allows them to convert the time to their respective time zones.
This unambiguous representation of data reduces the time that could be wasted when developers consuming your API repeatedly return to the documentation to understand your intent.
Maintain Consistency
Consistency is key. Be consistent in your naming conventions.
This is the most important thing to remember while developing an API. It doesn't matter how pretty or clean your code is if it doesn't work the same way everywhere.
Let's say that you request a date i.e. object from the server, and you code it with a particular name. You need to be able to request it from any other place in your code and get that same variable name back from the server. If you try to request it from a different place, and you get a different variable name instead, that will not work well for the consumer.
Always use unique identifiers to refer to individual objects in the collection and treat each one independently.
Validate Data
When building a web API, authentication is a crucial part of your security strategy that you should consider carefully. Even if you have an internal API that is not exposed to the public internet, it is still a good idea to follow best practices for authentication.
While consuming an API, don’t trust the data you receive. For instance, always re-validate requests in your backend, and all requests requested from the client should be treated with zero trust. You can never be sure what the client has sent, so always validate it in your backend.
Also, the client should not supply more information than required or overload the server. A rate limit defines how many requests a user can make within a specified time period, which prevents overloading the server with too many simultaneous requests from the same user. Rate limit your API if you have a free tier, or if it is publicly available.
Perform Introspection
Having the functionality to know when code was modified, and in what ways, is very important. It is most beneficial for large-scale teams. This will allow a team to work more efficiently and debug more effectively.
It is also handy to have some sort of version control so that you can revert back if a mistake is made. This will save developers time by not having to track down issues.
Version Your API or include data for introspection so you can trace events; know when a particular piece of code was created, updated and deleted, or archived. Even though you don’t send it to the client, it should be stored on the server to help the team track information much later.
Create Documentation
Don’t forget about documentation. This is the most important part of a good API. If you don’t have any documentation, then it will frustrate developers trying to use your API and they may just decide not to use it at all.
If you’re building a RESTful API, the most common type right now, you’ll need to provide documentation for your consumers. You should include everything they need to know about how to interact with your API to make the implementation successful. This can be done through a formal technical document, but also through a website. This way they know what sort of response they should expect and can write their own code accordingly.
Make sure there are no broken links in your documentation–this will make it harder for developers when trying to find the information they need while making an API call or looking at its response body (response content).
Other technical implementations based on Restful principles would include:
- Use HTTP Status Codes Appropriately
- Error Messages should be specific and descriptive
- Don’t Reveal Sensitive Information in Error Messages
- Use JSON instead of XML
- Handle PUT, POST, and DELETE correctly