Building REST APIs the Right Way

Let’s be honest, if you want developers to make use of your APIs, you need to make sure they deliver. And despite the incredible functionality and value your API brings to the table, if it is not designed or implemented well, it may never become a cult favorite or something developers are going to recommend to their peers.

Just like any interface, the goal with an API should be to provide a seamless experience that gets users (developers) building fast and easy. And this is not something that happens by mere chance or luck, instead, this is something API teams need to force into existence.

While there is no certain formula to build APIs developers love, there are a few practices and patterns you can follow to ensure you put out the best for your users, something that is familiar yet comfortable and gets them to complete their desired actions without any sort of hassle.

In the blog, we will discuss some of the steps you can take — from design to consumption — to ensure you end up with APIs that see both developer popularity and adoption.

1. Think, Plan, Strategize

“Give me six hours to chop down a tree and I will spend the first four sharpening the axe.“ ~Abraham Lincoln

Every good thing starts with a plan, and that’s how you should start with your API. You cannot simply come up with an API just because you want to, you need to put solid research into it. You should know what kind of users are you targeting, why would they want an API from you, how are they going to make use of that API and what value are they going to get out of it. Understanding the market is also crucial, do you have competition already offering what you have? How are you going to top them? Can you even compete in your niche? If not then is it even worth working on it?

Once you have answers to these questions, work on your Business Model. Decide if you want to go for an External or Internal API? In the case of External API, would you like to open it to the Public or your Partners only? Plan how would you monetize it. You could start from the freemium model but then again can you really afford to do that? Always remember the strategy you chose to address these concerns should be well aligned with your needs and objectives.

When planning, it’s also important to list what your API needs to do. List in detail, the features you intend to implement, at this stage you don’t need to worry about “Hows”, just focus on the “Whats”. Involve your potential consumers if you can, take their feedback, and prioritize your efforts accordingly. Build user stories and personas based on that feedback and make sure your use cases qualify for that.

2. Design is Everything

Once you are done with the initial planning, you need to translate that to design. Many API teams will miss out on the step and jump straight into development, and then go through several iterations over and over again to perfect the initial architecture. But with changing times and practices the Design First approach is becoming more of a hit rather than a miss.

With the approach, your plan is converted into a human and machine-readable contract called the API Description. The description exposes all of your resources and methods and helps you identify bugs and fixes in the early stages of your API. To execute this you can make use of design tools such as Stoplight or Mulesoft, or APIMatic’s own specification editor.

Designing your API before implementing also allows you to take user feedback with the help of API mockups. You can incorporate this feedback into your work to make sure you end up with a flawless product. A well-composed API Description can also be effectively used by your developers to understand how to best work with your API.

It’s really important to adhere to your Design throughout your API Lifecycle and if any flaws are recognized during the implementation phase, you should go back to ground zero to alter your design instead of making amends on the go.

3. Code For a Developer

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” ~Martin Fowler

Always remember when working with APIs, you are essentially producing code for developers, and for that reason your code should be fairly simple and self-explanatory. Not every developer in the world works with the same tools hence your code should not be tied to a certain technology stack and should be consumable in any environment. There are certain norms and conventions you can follow when implementing your API and although not the word of law, can really help with API adoption.

4. Taxonomy Runs the Show

Your API should require as little Documentation as possible to get running. Conforming to the correct taxonomy and naming conventions is the key to that.

Starting with Resources, always use nouns and in the plural form to name them. This keeps your resources flexible and decoupled from your methods and actions. Avoid naming Endpoints as such:

/createaccount
/deleteaccount
/listaccount
/editaccount

Verbs as you can see, are tightly coupled to a specific action and limit your resource. But by using nouns and then taking advantage of HTTP Action Verbs such as (GET, POST, PUT) you get the freedom to reuse resources, which enables you to accomplish multiple tasks.

Ideal endpoints should look like this:

/accounts
/accounts/1/names
/customers

It’s very important that you never deviate from the norms and conventions to not mislead developers. For instance, when working with HTTP Action Verbs, use the standardized commands for each action. To create a new record, always use “POST”, to read a record, use “GET” and similarly “PUT” and “PATCH” when making updates, and “DELETE” to delete a record. Mixing these up or not using any of these verbs for their intended action such as passing the data as query string when telling developers to use the “POST” command could cause utter confusion.

Another case where following the correct taxonomy is very important is with error messages, always effectively communicate with the developers about what’s going wrong, for example: in the case of REST APIs, use the standard HTTP Error codes to avoid any confusion. Other popular error message formats include Google Errors, vnd. error, and JSON API’s error format.

5. Multiple Data Formats Will Keep Your API Alive

When working with APIs, JSON has been the format of choice for many, but often your consumers may find themselves working with a different data format. For this purpose, always use a Content-Type Header which decouples your API’s dependency from a certain format. A Content-Type Header can easily determine what format of data are users requesting so your API could respond to them accordingly. Also, technology keeps on changing and evolving, and just like JSON replaced XML, we may (or may not) see YAML replacing JSON in the future and to avoid your API from going obsolete it’s only logical to support as many data formats as you can.

A sample query with a content-type header in HTTP looks like this:

POST /sample HTTP/2.1
Content-Length: 74567
Content-Type:multipart/form-data; boundary= — — — — — — — — — — — — — -974767299852498929531610575
Content-Disposition: form-data; name=”description” 

6. Hypermedia: A Dilemma

(HATEOAS) or Hypermedia as the Engine of Application State is another great practice to assist developers to consume your API. With the hypertext links, you can easily guide developers to discover paths and features right when they are implementing your API.

For Example:

• The following code contains an Account Object:

class Account {
    String name;
    String id;
}

• A normal JSON response is normally rendered as:

{
    “name”: “John”,
    “id”: “1”
}

• HATEOAS response will look like this:

{
    "name": "John",
    "links": [{
        "rel": "self",
        "href": "http://localhost:8080/account/1"
    }]
}

Here, “rel” means relationship, and “self” means a self-referencing hyperlink. The “href” is the URL address that uniquely defines the resource. Concise instructions as such make it really easy for developers to navigate and make calls.

HATEOAS is also a great way to introduce new features. Instead of making developers go through release notes, you can just direct them to new paths and actions using these hypertext links. Although not completely killing the need for documentation, HATEOAS has greatly reduced the reliance of developers on API documentation for every other call.

Where many people believe in hypermedia as the means of defining user experience, there are some that consider it as unnecessary bloatware. The common thought is, you are developing an API for a completely unknown consumer and it’s impossible to provide valuable information to direct the user or client to the next possible action. Some even argue that by adding additional links to your responses, you are increasing the load on your servers, marginally slowing down your response time.

However, despite skeptics, many API frameworks now include hypermedia specs and it’s something that is being widely adopted. When done well enough and supported with thorough documentation, hypermedia will always help with the consumption of your API, that’s what we believe in.

7. Test Everything

Your API should be thoroughly tested before every new release. Create test cases for all possible API inputs combination, test for failure, and invalid parameters. Test how your API deals with unforeseen circumstances and make sure they are dealt away with proper response codes. Stress-test your API as well, see how it handles the additional load. Run “Data Type Validation” tests, to confirm the data connected to objects is accurate and that all URLs are properly formed. All routes should be tested as well to verify that they invoke the correct operation. Ensure that there is no mismatches between routes. Also, verify that routes are protected properly with suitable authentication methods.

Test all possible combinations of request headers that a client can specify and make sure that your API responds to them accordingly. In case objects demand parameters, test query strings as well to see if they produce the desired outcome.

There is no GUI available when working with APIs which makes it really hard to test them but there are certain tools such as  Postman and Request Bin that can be used to make API testing easier. You can specify test cases when designing your API as well in the API Description, and there are services that will generate test cases for you in languages of your choice.

Again, at end of the day, an API is a software product and like all software products should be completely bug-free and should work as described and expected and you should make sure of that.

8. Version When Necessary

Even perfectly designed APIs may require updates to keep up with changing needs and requirements. It’s really important to version and document these changes with every new release.

Ideally, your API should be decoupled enough that any change you make in the background is a seamless transition but in case of major changes it’s important to ensure that your latest releases are compatible with previous versions. It’s also important to ensure that your system does not come to a halt while you are updating it. Even momentary pauses may cause a loss of quality when it comes to API Calls and functionality. Releasing too many versions can also confuse your consumers, versioning may not be the best approach for every situation, like adding new endpoints, supporting newer data types, etc. do not warrant a new version. Only version your APIs when:

1. You had to completely overhaul your API because your functionality is completely deviating from the evolving needs of your consumers.
2. You made some extensive changes to your API like renaming operations, removing operations, made changes to operation parameters, or made changes to the primary data types.
3. You introduced new technology at the backend which makes it impossible to make your API backward compatible.

How you version your APIs is also important, many API Providers put the version number in the header, some put it in the query parameter but the most popular and consistent approach has been to add the version notation to the URI/URL Parameter.

9. Authenticate, Limit, Throttle

It’s really important to authenticate the access to your API and limit usage where applicable. This can be done by providing your API users with a unique token or a key. Using the token/key you can monitor usage and set permissions/SLAs for your consumers depending on their needs. You can restrict usage as well, for example setting the limit to 5, 50, 500 calls per second to prevent abuse of your resources, ensuring all users get the same performance out of your system. This also helps you filter out power users, who you can pitch enterprise solutions to according to their need.

The industry standard when it comes to authentication is OAuth 2.0. Along with helping API providers with control access and limitations, OAuth 2.0 also helps consumers with improved security and better end-to-end experiences with web and mobile apps. Security is really important for consumers and when done right could be the sole reason for developers to opt for you over a competitor API.

10. Consumption is Success

“You’ve got to start with the customer experience and work back toward the technology, not the other way around.” — Steve Jobs

You can put in all the hours in the world to research, plan, and develop your API and still not see success when the Customer Experience, in this case, Developer Experience is poor. Just making an API is never enough and should never be the goal. You have to maintain and operate it in a way that consumption stays as smooth and seamless as possible. Your API cannot be truly successful when it’s not easy to consume.

11. An API is as Good as its Documentation - and SDKs!

Unless your API is open-source, Documentation is the only medium of communication between you and your developers and when it’s not clear or well presented, developers will always have problems using your API.

Ideally, a developer should get up and running with your API in minutes and your documentation is the key to that. Your documentation should be able to put developers in a position where they can start making calls instantly. Complete API documentation requires more than just your API reference in HTML or PDF form. It requires having a developer portal that pulls together everything that they will need to be successful. You can also offer an API Console on your Portal to let developers experiment with your code.

Put out SDKs (Client Libraries) in as many languages as possible to maximize your adoption rates. With your SDK, provide a complete guideline with tutorials and sample code snippets so developers can use them to communicate with your API with the minimum of effort. SDK generation however is not that simple and requires a lot of man-hours and effort to put together.

In fact, both Documentation and SDKs aren’t something you can easily produce from scratch, also with constant updates and new releases, it may become impossible to maintain them, especially if you deal with different languages. However, there are certain tools that you can use to generate SDKs and Documentation in real-time without having to write a single line of code. Our own in-house Developer Experience Portal is a great way to get developers started with your API. Just give us your API descriptions (we accept over 15 different formats) and we’ll generate a whole API Portal for you, complete with SDKs, Documentation, User Guides, and Live Code Samples. The portals are completely customizable and can be integrated with your current systems and will and take just minutes to set up.

Since Documentation is the face of your API, it should be one of the most important things on your agenda. When considering an API, the very first thing developers look for is documentation and when done nicely, it can easily drive them to test your API, which ultimately leads them to adopt it.

12. Ensure Responsiveness and Scalability

Another important aspect of API consumption is your infrastructure underlying it. It’s really important to ensure that developers are facing no problems when actually accessing or making use of your API. Your API may be utilized by many at the same time and it’s important that it stays responsive under heavy load. To make sure your API stays scalable enough to support a highly varying workload, it’s essential to make use of an API Gateway. The API Gateway integrates with your backend services and acts as an orchestration layer governing everything that interacts with your API. Ideally, an API Gateway should provide the following services:

1. Control and automate the connection between an API and the client applications making use of it.
2. Monitor traffic from individual applications. APIs can’t handle unlimited calls and it’s really important to throttle requests.
3. Provide caching mechanism to improve response rates.
4. Secure API using various procedures to prevent misuse.

Concluding this all, we’ll always advise API Developers to keep their APIs as simple as possible. It’s important to think like an API User instead of an API Designer, most API users are looking to make their lives easy and if your API is not helping them achieve that objective, it’s probably not a very good one. When it comes to API development it’s never about what your API does, it always about how it does it, and the easier, the better.