Providing a Web API for your system – An introduction

Imagine wanting to develop an application which has the main purpose to store, process and deliver data. Your data model is mature enough, you have a decent interface in place. Basically, the whole application is functioning well as a whole and is technically fulfilling its primary requirements. But what is the next step? The users of the platform might want to run statistics or analysis? The interface is not to the liking of all users? Or maybe it would be nice if the platform could be used from other applications through integration with add-ons or such? How would we go about that?

The simple answer to this question is to provide an API. An API is an interface, with which developers can communicate with your application through other software they’ve written. This answer by itself is likely to invoke other questions. Questions regarding security for instance: Is this technology safe? Is it keeping all the bad people out? Can I restrict this functionality to certain users only? Questions regarding accessibility: How should I be presenting my data, and in what format should I accept it? And many other.

This series of posts gives an introduction about what an API does, who it is for, and how it is used. It highlights a few considerations or problems that will occur during the development process as well as the preferred solutions. (In most cases, these would be the industry standards)

(We’re going to have to make the assumption that we’re indeed going to be developing an API for a system that stores, processes and delivers information. Systems that execute instructions (Like a robot, for instance) require a different form of API.)

What does the API do?

The API will do exactly what was described in the introduction. It provides an interface for developers to communicate with your system/application. If we take a few well known applications, we know that for instance Twitter, Facebook have API’s, and Google even has a whole bunch of them.

What these API’s provide is the opportunity to provide functionality that the original products don’t have by enthusiastic developers that are not employees of these companies. In the case of Facebook, imagine writing an application that delivers statistics on your friends list. Which of your friends comments the most on your posts and who just presses the like button a lot? Or maybe you want to automate posting a news flash on each of your social media, every time you publish a new article on your blog without having to do this manually? This is what API’s are ideal for. Extending the functionality and accessibility of your existing applications/products.

Who will the API be for?

The people that will be working with your API will likely be software developers. These developers will likely have worked with other API’s too. In the ideal situation, you’d like for them to have little to no learning curve regarding working with your API. Therefore it is important to focus on standards and making the API as intuitive as possible.

There are multiple standards for creating an API. The more well known technologies are REST, SOAP and WSDL. Our focus will be on REST, as this is the most well known and most adopted variation.

How is the API used?

Here it gets a little bit more technical. REST stands for Representational State Transfer. This means that every resource request, as well as the responses, represent the full state of the entity. These resources are likely to be objects from your application’s data model, or composites of it. In simple terms, a resource should be able to be represented as a noun. These could for instance be ‘cats’, ‘dogs’, or if you want to be more generic ‘animals’.

The resources are accessed or manipulated by sending HTTP requests to the server. These requests can be made using any application that has a form of HTTP client, for instance a browser like Chrome, Firefox or Edge. The request ‘methods’ define the ‘verb’ being applied to the resource and provide your basic CRUD functionality. It maps as follows:

• GET /cats – Reads/Provides the list of cats
• GET /cats/1 – Reads/Provides the cat with ID 1
• POST /cats – Creates a new cat
• PUT /cats/1 – Updates the cat with ID 1
• DELETE /cats/1 – Deletes the cat with ID 1

There is one other verb which is not always implemented, as it doesn’t represent a full state of an entity. This is the ‘PATCH’ method and is often ignored during implementation as it kind of doesn’t support the full REST principles.

• PATCH /cats/1 – Partially updates the cat with ID 1

It is common practice that the names of the resources are pluralized, this avoids getting inconsistent names like GET /mice and GET /mouse/1.

What about security?

Your system might contain personal user data, confidential data or otherwise sensitive data that you do not want to have accessible to everyone. The classic solution is to have a user account for each user that would restrict what he/she is eligible to see. This user information would be cached on the server in form of a ‘session’. By maintaining this session between the user and the server, the server knows what it is allowed to deliver back to the user and what not.

For the Web API, this scenario would not be applicable, but a very similar solution is available.

Instead of these sessions, the Web API could work with tokens (For instance JWT tokens) .These tokens can be seen as a temporary claims of trust, that allow for an external application to communicate with the API of your system. These tokens typically contain the information of the application that is using the token, information regarding the user of the system, and some information regarding the validity of the token. (Example: The application is the previously mentioned Automated-Social-Media-Updater, the user is either your company’s Twitter or Facebook account and the validity would be 5 minutes since creation of the token.) In order to prevent the token from being tampered with, these tokens would also contain the claims in an encrypted format. The server can then compare the encrypted and the non-encrypted information, in order to determine what the user has access to.

Is that all there is to it?

The short answer is ‘no’. There are many more aspects to developing a RESTful Web API, but these are the primary topics for an API from a product and/or business perspective. Future posts will contain a more in-depth approach on how to tackle the various challenges that will come up during the development of a Web API. The focus will then also shift to actual implementation, rather than a high level implementation.

This post will be updated with references to the follow-up posts once they are posted.