Maintaining and designing scalable APIs is a tremendous task, especially once you have more than 100 APIs for your project. In the era of API as a Service, knowledge of API design is unavoidable.
In this article, we will discuss a few RESTful API design standards you can apply to your projects for building an ideal API ecosystem.
Focus on Resources
The fundamental purpose of APIs is to provide access to particular resources. An API resource represents a piece of data or functionality that the API provides access to.
For example, in a CRM (Customer Relationship Management) application, typical resources include:
- Contacts
- Leads
- Accounts
- Tasks
A resource can be in the form of a singleton (a single account) or a collection (a group of tasks).
We can design an API in the format GET /contacts to fetch a list of all contacts or PUT /tasks/301 to update a task's details.
Proper URL Naming
Naming conventions are important for URLs. It is better to use nouns for RESTful URLs, as RESTful APIs are designed for collecting resources and communication, not for performing actions or operations.
Recommended Approach
GET /contacts
GET /tasks/:id
Less Preferred Approach
GET /get-contacts
GET /get-task-by-id/:id
Use Path Parameters
Using path parameters provides a clear and structured way to identify resources and their relationships within the API.
GET /tasks/:id
Avoid this
GET /tasks
{
id:1
}
Maintain API hierarchy
Maintaining a well-defined resource hierarchy helps define relationships between different resources in an API.
In the case of CRM
GET /user/{userId}/task/{taskId}
Here, the API clearly fetches the task based on the task ID under a specific user.
API versioning
APIs will get modified as the product grows. So, modifications to the API should not affect older users, older clients, or frontend code. That's when versioning comes in.
Use API versioning when:
- Renaming or changing any endpoint or property
- Parameter changes
- Modifying a data format
Versioning can be done by using URL Path Change or by using a Header.
URL Path
Version is defined in the path itself.
Example: https://example.com/api/v2/user
Header Versioning
Version defined in the Header of the API
Accept: version=1.0
Maintaining and designing APIs is a never-ending challenge. It will differ for different products, use cases, and contexts. This article covers a few aspects that will help you to build better API ecosystems.
My team and I are developing LiveAPI, a super convenient API doc generation tool. Using LiveAPI, you can create API documentation for any web project within minutes, with minimal effort.
Also, once you connect, LiveAPI will keep your API documentation up to date based on code changes.
Try LiveAPI and share your valuable feedback. Keep connected for more tech tips and articles.
Top comments (1)
Good overview of common API design mistakes.
The section on resource hierarchy and API versioning is particularly helpful.