Avoid mistakes in these 9 Key areas of your REST APIs
By: Avishek Jana
Tags: Design Patterns, Rest Api, Api Development, API, Rest

APIs are the engine of modern software development. In this article, I’ve pointed out 9 key areas of REST APIs where you are making some mistakes knowingly or unknowingly during both design and development phase. Starting from API endpoints to API security, these mistakes make our API, less developer friendly and less REST alike. Developers, who are willing to write an application around them, would find it difficult to integrate and consume.

So bookmark this article and go through it once before you start designing any API services.

9 Key Areas

1. API Endpoint

Every API needs an endpoint URL and this is a common scheme to follow

API Endpoint Structure

⚡️1.1 Now for the endpoints, the first part is the Base URL, which has the domain where the API is hosted. Make sure to use a subdomain for your base URL.

⚡ 1.2 Use a package name for logical grouping of your resources. For ex. let's assume you are creating APIs for a banking system. Now banks have credit card accounts, savings accounts and loan accounts. And it may be possible different teams are working in different account types. In this scenario, this pa will help you keep these resources separate at top level. Ex. https://api.mybank.com/loan/v1/accounts

⚡ 1.3 Use versions to insulate API consumers from API changes. By having version in the path, makes it easier for users to switch between the versions.

2. Resource Naming

The fundamental concept in any RESTful API is the resource. A resource is an object with a type, associated data, relationships to other resources, and a set of methods that operate on it.

⚡ 2.1 Don’t use verbs to name resources, always use nouns.

⚡ 2.2 Keep resource name in plurals

Ex. businesses, accounts, people, products etc.

3. Resource Associations

RESTful resources can have associations or relations with other resources. For Ex. Order have Order Items, User has Profile, Profile have Followers etc. These relationships may be identified within an endpoint URL for the API.

For Ex, to find all followers of a person on Twitter, the endpoint would be like: /people/{id}/followers

Similarly, Expedia provides an API for getting the amenities for specific room types within specific properties, and the endpoint would be: /properties/{id}/roomTypes/{id}/amenities

So my suggestion for resource association is:

⚡ 3.1 Don’t use more three level of nesting while specifying relationships between multiple resources. But if you do have such requirements, consider using subqueries to avoid this deepness.

4. Resource Operations

CRUD (Create Read Update Delete) operations that can be carried out on the resources exposed by APIs. For these CRUD operations, one need to invoke the endpoints for the API using an appropriate HTTP method.

But what if the operation that need to be carried out on the resource is not a CRUD operation?

⚡ 4.1 If you have such a requirement for defining an action on a particular resource, then define that action as part of the resource hierarchy.

For example, UBER provides an action to estimate the price of a ride by way of /rides/calculate_price

5. HTTP Verbs

⚡ 5.1 Use appropriate HTTP verbs for CRUD operations.

6. HTTP Codes

An HTTP server always sends back the status code and the status response text in the header. The status response text is an informational message related to the status code. As an API developer or designer…

⚡ 6.1 Don’t invent new codes — Use the standard HTTP codes for your REST API.

⚡ 6.2 Don’t use more than 10 HTTP codes throughout all of your APIs.

Recommended ones: 200, 201, 204, 400, 401, 404, 422, 500

7. Data Formats

RESTful APIs are not tied to any specific data format (like SOAP is tied to XML). The representational state may be converted to any format such as JPEG, PDF, Excel, etc.

⚡ 7.1 Keep JSON as your default data format, as JSON now has become the de facto standard when it comes to modern APIs.

⚡ 7.2 Define proper strategy where client would define the requested data format. Ex. In query parameter, HTTP header or in resource suffix.

Query Parameter: /news?output=json

HTTP Headers: Accept: application/json

Resource format suffix: /forecast/daily/{days}day.json

8. Error Handling

The error information sent back to the API client is meant for use by the application developer. Here are some guidelines for designing your error response.

⚡ 8.1 Send error information in both HTTP Header and Response Body.

Using both HTTP Header and Body to send error response

⚡ 8.2 Don’t use multiple error response formats.

The idea behind this is, if you’re using different error message formats across your APIs, the developer will have a challenge dealing with different APIs with different response schemes.

⚡ 8.3 Error response should be informative, actionable and consistent throughout all your APIs.

For example, the API may send back the name of the field, which is a required field, and the app developer can use the name of the field to highlight on the interface, that the field that needs to be fixed by the user.

⚡ 8.4 Define and use application level error codes. Ex. validation_error, internal_server_error, request_quota_exhausted etc.

The idea is, these status codes are unique string in nature and these status codes can be used by the application developer or the API client to put together the application logic for managing these errors.

Sample error response

9. Security

We often forget that APIs are not meant to protect data, rather, to share data across applications. And API providers are certainly responsible for designing their APIs to be secure. API security have three main aspects: Authentication, authorization and the functional attacks that may be launched. Let’s find out the recommendations and mistakes to avoid.

⚡ 9.1 Don’t use HTTP Basic authentication without HTTPS.

In HTTP Basic Authentication, the consumer sends the credentials to the API server in the HTTP header called Authorization. The data in the Authorization header is a base64 encoded string, in user:password format. That means the user and password are going to be visible to anyone who’s carrying out the man in the middle attack. So the bottom line is Basic Authentication is OK to use with HTTPS only.

⚡ 9.2 For Token Based Authentication, make use of JWT.

⚡ 9.3 Use OAuth 2.0 as your Authorization framework.

As API provider, you have to make certain design decisions for implementing OAuth.

The first one is scoping of the user data (what data for the user is public and what is private) Next one is the type of OAuth Grants that you would support for your APIs.

⚡ 9.4 Consider implementing security features to protect your APIs from functional attacks like: SQL injection, Cross Site Request Forgery, Fuzzing & Session Hijacking.

In a functional attack, the hacker tries to understand the functional weaknesses of the API, and then they launch an attack using those functional weaknesses.

The solution to functional attacks are:

Test & Monitor continuously, invest in tools. Select an appropriate security model for API. Consider an API gateway or API management platform.

Wrap Up

REST is a design pattern defined by the community. What I’ve shared above is coming from my experience and knowledge of developing APIs for the last 8yrs. You are always free to improvise it as per your need. Though if you keep these 9 key areas in mind from next time onwards, your APIs would be no different to other unicorns like Uber, Spotify, Twitter etc.

I’ve defined a timeline for a series of such articles on API, which I’ll publish every week. Do follow me and subscribe to newsletter to know more about those updates.

Thanks for reading!!

If you have any questions or suggestions regarding this article, feel free to comment down below. Peace!