This article will be an API Primer into how to name an API to match industry standards. we will deep dive into how REST API name and conventions are to be setup. Name here is an overloaded term which can map to endpoint or various aspects of a REST API specification.
REST APIs are the backbone of modern application. The most prevalent is REST APIs, with SOAP becoming legacy and GraphQL seemingly emerging as the next step in API evolution. Further APIs and API monetization is growing (at a CAGR of 23%), hence demand for technical skills is high
This series will provide insights into the various aspects involved in building REST APIs
Let’s start with defining APIs
Name Conventions
Here are some of the best practices that we can follow, (NOTE: no defined standards for REST API naming)
- Endpoint definition
- Query parameters
- Headers
- Payload
Endpoints
<HTTP Method> <version>/<resource>/{id}/<child-resource>
An example and recommendation is to limit levels of nesting to 2 like GET departments/{dept-id}/employees/{emp-id}
Some examples to reinforce the convention and avoid common pitfallshttps://prashant-prasannakumaran.medium.com/media/966c88769ba47094007e96efd3d7f610
The scenario’s were verbs start appearing in URL are the more tricky ones to manage
PUT versus PATCH
- Use HTTP PUT Method when we need to update an entity (like Edit Entity)
- Use PATCH when wanting to update parts of an entity
- Creating a dedicated endpoint for specific changes which need dedicated business logic benefits to monitor and derive insights
Path Parameter
When: To provide a resource identifier for GET, PUT, PATCH, DELETE requests
Examples pass bookId in the path /v1/books/<bookId>
- Fetch details of a particular book
- Update details of a particular book
Query Parameter
When: To provide filters, sorting, pagination parameters for GET requests
Note: Use with GET requests only
Recommendation for pagination
- limit=number
- offset=number
Recommendation for sorting
- sortField=
- sortOrder=asc|desc
OR
- sort=-[incase we want desc]<fieldName>
Headers
Ensure we use Standard Headers wherever applicable for scenario’s like requesting a response format (Accept), language (Locale), identifying an user (Authorization)
Custom Headers to be added when we want to pass information that is applicable across APIs e.g. CSRF tokens
Recommended naming convention: X-<name>
If the name has multiple words, split them by hyphen
Payload
For pagination scenarios include fields like limit, offset and totalCount
Ensure related fields are group together into objects
Generic Aspects
- Do remember to use payload to send data via POST/PATCH/DELETE requests instead of query parameters
- Ensure camelCase or hyphen-case or snake_case are used when resources or payload attributes are having multiple words. Pick any of the styles and follow them consistently
Next Steps
Lookout for more content around other aspects of REST API development
More articles about REST APIs are available here