Table Of Content
Because there were a lot of legacy Swagger documents, it’s important to have a compatible community-owned version. But API practitioners wanted to move the OpenAPI specification forward with OpenAPI v3, with its latest release being 3.1 in 2021. Just like website design or product design, API design informs the user experience. Good API design principles meet initial expectations and continue to behave consistently and predictably. When you make a REST API, you need to help clients (consumers) learn and figure out how to use it correctly. The best way to do this is by providing good documentation for the API.
Use an international design standard
So it would be a wise decision to move the services folder also into a specific version folder. There are many different approaches to handling versioning inside an Express API. In our case I'd like to create a sub folder for each version inside our src directory called v1. One good practice is to add a path segment like v1 or v2 into the URL. The script makes sure that the development server restarts automatically when we make changes (thanks to nodemon).
Step 2: Define the API contract with a specification
These relationships allow you to pull a larger group, or break into that group for a specific item. You also can use PUT to create IDs if the client itself selects the ID number. Frequent deployment of individual APIs can quickly create a software system that resembles an overgrown garden, weed-ridden with bugs, broken integrations and ill-fitted use cases. Bloated collections of APIs make it hard to make changes without causing failures, or even gain the visibility to recognize opportunities for improved functionality. There are many kinds of caching solutions like Redis, in-memory caching, and more. To enforce the principle of least privilege, we need to add role checks either for a single role, or have more granular roles for each user.
Use Plural Nouns For Name Collections
When crafting APIs, the primary design principle should be to maximize application developer productivity and promote adoption. When you make REST APIs available this way, you are not forcing clients to migrate to the new versions in case they choose not to. If this happens, retrieving data from such a database could be very slow.
Use Nouns Instead of Verbs in Endpoints
Clear and consistent endpoint names make it easier for Moesif to categorize and group API requests, leading to more accurate reporting and insights. Additionally, using descriptive names in endpoints aligns with Moesif’s functionality for user identification. By following these conventions, you can ensure that Moesif accurately tracks API usage by specific users, providing valuable data for targeted analysis and informed decision-making. Endpoints within REST APIs, also known as REST endpoints, serve as interaction points, allowing specific URLs to be configured to receive web requests.
Paths of nested resources should come after the path of the parent resource. They should tell us what we’re getting or manipulating without the need to read extra documentation to understand what it’s doing. We can add caching to return data from the local memory cache instead of querying the database to get the data every time we want to retrieve some data that users request.
Like I said, I'd like to start with our fundamental CRUD endpoints. You've just structured the project for handling different versions. We are now passing incoming requests with "/api/v1" to our version 1 router, that will route each request to the corresponding controller method later. Before we write any API-specific code we should be aware of versioning. Like in other applications there will be improvements, new features, and stuff like that. After that we'll be extending the API with each best practice.
How to Tame Your Service APIs: Evolving Airbnb's Architecture - InfoQ.com
How to Tame Your Service APIs: Evolving Airbnb's Architecture.
Posted: Fri, 11 Jun 2021 07:00:00 GMT [source]
This approach is quite useful if a project is about developing externally exposed set of APIs which will be consumed by partners. In this world of microservices, a consistent design for your backend API is imperative. But this violates the property of stateless APIs, which is when an external user handles the storing of session-related information on their end. You can break the response down, like return the first thirty users, the subsequent thirty users, and the following ten users. Pagination is a method of separating digital content into different pages on a website or a response object. Imagine we want a user to be created as an admin under the admins' group table.
The good thing about caching is that users can get data faster. This may also lead to issues when debugging in production environments when something goes wrong as we keep seeing old data. To eliminate confusion for API users when an error occurs, we should handle errors gracefully and return HTTP response codes that indicate what kind of error occurred. This gives maintainers of the API enough information to understand the problem that’s occurred.
They allow clients to customize the API response to suit their needs, leading to more efficient data transfer and improved user experience. How can you ensure that your API is flexible, extendable, agile, and accessible to other developers? This section answers this question by demonstrating the value in using nouns – not verbs – as resources, applying CRUD, using JSON, and other best practices.
They immediately know to go inside the request body and see if they've missed providing one of the required properties. To improve the experience we also can send a quick error message along with the error response. But as I've written in the introduction this isn't always very wise and should be considered by the engineer themself.
