Introduction
Picture this; you are in an interview for a front-end developer role after mastering all the front-end questions related to the companies stack. Then you are thrown a curveball question: "Can you tell us the characteristics of a good API design?".
And you are stunned.
Sure, you have worked with countless public and private APIs, most of the time without speaking to the developers who designed the APIs. But due to the abstraction in modern front-end frameworks and libraries, most front-end developers do not know the characteristics of a good API.
React get request, Source: reactjs.org
Axios post request. Source Axios, GitHub
These are valid API calls, and you will find them in this format in most modern applications, nothing about the status codes or the shape of the response, errors are handled elegantly with Promises.
But that doesn't mean you won't get API questions for front-end roles.
Attributes of a good API design
Below is a list of some of the attributes of a good API design; the list is not exhaustive, but it will be sufficient to demonstrate your knowledge of API design.
- Use JSON
- Use nouns of verbs and nouns
- Use resource nesting
- Error handling
- Filtering, sorting, paging, and field selection
- Versioning
- API documentation
- Using SSL/TLS
Use JSON
JavaScript Object Notation (JSON) is a lightweight data-interchange format that is readable and is easily parsed by machines. JSON should be used for requests and responses. Most applications have a way of encoding or decoding JSON. As a result, it is now a universal standard of transferring data that all developers have come to expect.
Use nouns in the URL and verbs for API methods
Verbs and nouns have their place in API endpoints. However, verbs are relegated to the API methods like GET, POST, PUT, DELETE and not the URL itself. In contrast, nouns should be used in the URL.
For instance, if you want to create a new user, instead of https://api.example.com/addUsers/ you should use the POST method and a URL like: https://api.example.com/users/
Similarly, if you want to delete a book, instead of https://api.example.com/deleteBook/[id] you should use the DELETE method and a URL like: https://api.example.com/books/[id]
Use resource nesting
Let's say you are running a book store and have authors, and those authors have books. To get the books written by a particular author, use this endpoint: https://api.example.com/authors/[author_id]/books. You can also have a books endpoint to retrieve a specific book by its id, like: https://api.example.com/books/[id]
Error handling
Use the regular HTTP response codes as defined here https://httpstatuses.com/ to describe what is happening. But sometimes, they are generic and won't tell developers what is happening, especially in a complex application. You can extend the error handling so that users know what is happening when something fails. Twilio's elegantly extended its errors; take a look at it here https://www.twilio.com/docs/api/errors.
Filtering, sorting, paging, and field selection
These are all actions that should be enabled on the endpoint that returns lists. For instance, include a field to limit the number of records shown like this on an endpoint that returns the author's books: https://api.example.com/authors/[author_id]/books?limit=[number]. If the endpoint user doesn't provide a limit when sending a POST request, default to a standard when returning results. This limit will be based on the nature of the application. Same with sorting: https://api.example.com/authors?sort_by=email&order_by=desc
Pagination is also needed; if not, an endpoint might return millions or billions of records, thereby affecting the server's performance.
And finally, field selection limits the number of fields returned from an endpoint and utilizes network resources efficiently. For instance, if we are only interested in the titles of an author's books. We can create an endpoint like this: https://api.example.com/authors/[author_id]/books?fields=title
Versioning
Over time, changes will be made to the API, adding new methods, data structures, etc. The developers should assess whether those changes will break the endpoints already in the wild and create new versions so that customers don't have to update their code whenever there are changes.
Documentation
Every API needs to be appropriately documented. The documentation should include the endpoint URL, the request payload, expected response payload, the method, and the required fields' data structure in the request payload. This is a sample of good API documentation: https://mailchimp.com/developer/marketing/api/
Using SSL/TLS
HTTPS protocol should always be used in APIs, and there are no exceptions. This provides an additional level of security of the API since some sensitive information is transferred through APIs, like tokens and passwords.
Top comments (0)