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)

1. Endpoint definition
2. Query parameters
3. Headers
4. 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

1. Do remember to use payload to send data via POST/PATCH/DELETE requests instead of query parameters
2. 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