Overview:

You have an idea for a project or an existing project in progress and it’s time to build a web API; do you know where to start? 

The following article outlines the initial topics to consider before coding a new Web API. Above all, take time to plan your API ahead of time in an effort to minimize the development errors and integration pains that afflict so many APIs. It’s not uncommon to come across APIs “in the wild” that are absolutely terrible to work with – don’t let your API fall into this group.

Consider these items before you write a single line of code and you will all but guarantee that your API will be functionally sound and a pleasure for client applications to interact with.

Which type of Web API is right?

There are many factors to consider when choosing the type of Web API you will build. Take a few minutes to read about the 3 common types of web APIs you want to use. When choosing the type of API keep the following in mind:

  • Will the clients need to access Resources directly?
  • Does a client application need the API to pre-process the result?

In the case that clients will need to access objects directly or by ID, a REST API might be a good choice. Mainly, this type of API is most appropriate for CRUD (Create, Read, Update, Delete) operations. A simple example would be the Twitter API – Create Tweet, Read List of Tweets, Edit Tweet, Delete Tweet.

If the client will be requesting data that has been pre-processed, an RPC API may be the best option. RPC APIs are usually addressed with URLs that contain verbs, these endpoints instruct the to take some action on the data or aggregate the data in a particular manner before returning the results. 

Remember that an API should strive for efficiency; it’s not desirable for the author or client if the client must always make multiple requests to the API when trying to get data. An inefficient API can lead to increased hosting costs and discourage potential clients from using it.

By predicting the kind of queries that your API will receive, you can build it to balance efficiency and ease of use.

Data Format

Choosing a data format is not as straight-forward as it seems. Simply picking JSON (JavaScript Object Notation) or XML (eXtensible Markup Language) is not enough. Within each data type there exist specifications that are widely accepted and documented. 

Deciding which specification to implement may have a great impact of the usability of your API. You may choose to expose the data in their native object format, serialized to the respective data type. However, by using a specification such as JSON:API or JSON-Schema, you can help to ensure that common scenarios of data access are covered.

Endpoint URL Format

Any savvy client application will want to build the URLs to your API dynamically at runtime. This allows the client to accurately replace the query and path parameters and call your API without hard-coding all of the possible URLs for data access.

Additionally, having predictable and highly structured URLs will make maintenance and extension of the API run more smoothly.

Let’s take a closer look at a set of structured RESTful URLs:

https://my-api.com/v1/user
https://my-api.com/v1/user/{id}
https://my-api.com/v1/user/{id}/device/{id}

Notice that the above URLs have a predictable structure and build upon one another to access nested data. Given these URL examples a client can easily understand how other data might be queried from the same web API by combining this pattern with the Base URL and Resource name.

Error Handling

While deciding on the data format of your API you may have come across different strategies for handling errors. Providing structure for errors is an important part of any API and should be a priority. Having a standard format for returning errors allows the client application to elegantly catch the errors and display relevant information to their users.

Note that errors which occur in the API and on the server itself need to be handled. In a production environment it’s not acceptable to have errors generated by the server or application that are not wrapped by the API and potentially obfuscated.

Some best practices for handling errors generated by your API are:

  • Create a separate error block in the return data
  • Avoid returning error and data in the same request
  • Do not return error with an HTTP status of 200
  • Use a reasonable subset of HTTP statuses – too many causes confusion and too few causes difficulty to use

Endpoint Versioning

It’s inevitable that your API receives an update. Whether it’s caused by bug fixes or new functionality your API’s data format, data fields, and URLs will evolve over time. When this occurs client applications may face breaking changes. If this occurs too often clients may choose not to use your API.

In order to avoid forcing your API clients to upgrade with each major update, your API should implement versioning. In most cases, this is done by adding version indicator as a path or request parameter. 

https://my-api.com/v1/users
https://my-api.com/v2/users

By incorporating the version into the URL of your API endpoints you will be able to have multiple versions of your API at any point in time; this allows for clients to migrate at their own pace and aids with the rollout of new features.

Wrapping up:

There are many more factors to consider when building your API and getting it ready for production. Just to name a few:

  • Logging
  • Monitoring
  • Authentication
  • Authorization

In summary, if you consider all of the topics covered in this article when putting together your API you will be well on your way to crafting an excellent piece of software.