5 Tips for Better REST API Design

DZone 's Guide to

5 Tips for Better REST API Design

Good API design is difficult. Maintaining backwards compatibility, effectively testing, handling upgrades, etc. is hard to manage. Check out this guide for help!

· Web Dev Zone ·
Free Resource

There is no doubt that "API" has become the de-facto standard for exchanging information between systems and also helps in better integration within components of a system. 

In this article, I will share some of the practices that I followed while working on multiple REST APIs design and implementation.

1. Client SDK Instead of Writing Our Own Code

If the vendor or the service creators have an SDK, then I prefer to use it for API calls instead of writing my own client library on top of native REST calls. A great example is the AWS SDK to interact with Amazon Web Services. Choosing to use AWS SDK helped my team to reduce the learning curve, start right away, and saved time to write logic to handle ā€” security, network timeouts, retries, fallback, etc.

Since these SDKs are maintained by the vendor, developers don't need to bother on the testing, fixes, and changes to support new API endpoints. Most of the modern SDKs are open-sourced and based on standard protocols (REST, WebSocket, gRPC) supporting rapid integrations.

A major disadvantage of API SDK is availability and support for programming languages of your choice. In such cases, developers need to develop a custom REST client. I always recommend developers to design and implement it as a separate Maven project, hosted in enterprise Git repo, well documented and available to all internal teams in your organization.

2. Swagger for Documentation

I can't emphasize how much beneficial swagger has been to API developers and most importantly to people who are not from any development background. It is also part of most of the modern development framework to make it easy for developers. As a developer, I can easily execute APIs and test instead of jumping to another document and reading lots of text. As a consumer of the API, you can understand the API, its params, expected payload model, etc.

I don't discredit a document which can have more detailed information (including sample payload), but I have found many such documents out of date with the current API version. In my opinion, use Swagger to complement documentation and help other developers to quickly start their integration.

3. Following a Standard Approach for Endpoints

When designing an API, many new developers don't follow a standard nomenclature of endpoints or don't defining operations in terms of HTTP verbs. There are many good resources available online which address this in detail, see references.

Few of the approaches I strictly follow and ask my developers to follow include: 

  1. Do not mix an upper case and lower case in endpoints. E.g. instead of "/users/userId" change to "/users/{id}". Instead of POST "/deleteUser/userId" better use DELETE "users/{id}"
  2. Always use versioning in the URL e.g. I follow "/api/v1/" as a mandatory part of URL
  3. Make "https" as a default option for clients to connect. 
  4. Have a validator for payload verification and it should be the first step in the code. Do not leave it for later processing and rely on catching all exceptions.  

4. Handling Upgrades

Imagine, your service uses an API to post some data, and suddenly it is not working. Later, after many emails and meetings you figured out that oh! there is a change in the payload that now requires a mandatory field. Well, the frustration is valid because the API was upgraded with no backward compatibility.

Such errors can be also detected early using any CI process, but as an API developer, you must think of existing clients while doing changes to APIs, such as for any new field in the request body, use a default value or define a new version endpoint like "/api/v2", etc.

5. Test

Don't just functional test but load test. You should know how many API calls per minute a server can handle. What is the response time when network latency increases. Many enterprise customers have their data centers spread across the globe or use a multi-region cloud environment. It will help customers if you can share benchmark numbers when you hosted an API server in US-West, and test clients from instances in US-East, EU, India, and Austalia.

I prefer using tools dedicated to API testing such as Postman, or Apache JMeter instead of writing one. They not only save time, but also allow me to export templates which I check-in to git.


One article can't cover all the best practices but hopefully, you should get a gist of things. I believe "API Development" is on par with other aspects of software engineering and sort of specialized area with a lot of scope for innovation.

Looking forward to your feedback.

api, api design, aws, grafana, network analysis, vpc flow

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}