API Primer — REST API s— what’s in a name…
API (Application Programming Interface) is the backbone of the digital world
The most prevalent is REST APIs, with SOAP becoming legacy and GraphQL seemingly emerging as the next step in API evolution.
APIs and API monetization is only 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
Naming Conventions
There are no defined standards for REST API naming, however there are certain best practices recommended for various areas like
- Endpoint definition
- Query parameters
- Headers
- Payload
Endpoints
<HTTP Method> <version>/<resource>/{id}/<child-resource>
It’s recommended to limit levels of nesting to 2 e.g. GET departments/{dept-id}/employees/{emp-id}
Some examples to reinforce the convention and avoid common pitfalls
The scenario’s were verbs start appearing in URL are the more tricky ones to manage
PUT versus PATCH
- Use PUT when wanting to update an entire entity e.g. Edit Entity screen
- 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
- Ensure POST/PATCH/DELETE requests do not send data via query parameters, use Payload
- 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
Credits
Thanks to Pranav Silimkhan for inputs and corrections
