Skip to content

About

Most modern web applications expose APIs that clients can use to interact with the application. A well-designed web API should aim to support:

  • Platform independence. Any client should be able to call the API, regardless of how the API is implemented internally. This requires using standard protocols, and having a mechanism whereby the client and the web service can agree on the format of the data to exchange.

  • Service evolution. The web API should be able to evolve and add functionality independently from client applications. As the API evolves, existing client applications should continue to function without modification. All functionality should be discoverable so that client applications can fully use it.

APIs are like the TCP/IP for applications. It specifies how applications interact and exchange data between each other. Like TCP/IP, RESTful APIs are stateless. All requests using the API have to contain as much information as possible for the server to identify the client.

The API specifies a set of rules for one application to interact with another. Many APIs have proper documentation that also describes the nature and structure of the response they send when you make a request. They also specify the necessary information a requesting application needs to provide to make a successful request to the API.

In effect, RESTful APIs function just about the same way standard TCP/IP requests function, except there are no clients and servers here, but just two applications talking to each other.

Like any other architectural style, REST also does have it’s own 6 guiding constraints which must be satisfied if an interface needs to be referred as RESTful. These principles are listed below.

Guiding Principles of REST

  • Client–server – By separating the user interface concerns from the data storage concerns, we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.
  • Stateless – Each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server. Session state is therefore kept entirely on the client.
  • Cacheable – Cache constraints require that the data within a response to a request be implicitly or explicitly labeled as cacheable or non-cacheable. If a response is cacheable, then a client cache is given the right to reuse that response data for later, equivalent requests.
  • Uniform interface – By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved. In order to obtain a uniform interface, multiple architectural constraints are needed to guide the behavior of components. REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state.
  • Layered system – The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior such that each component cannot “see” beyond the immediate layer with which they are interacting.
  • Code on demand (optional) – REST allows client functionality to be extended by downloading and executing code in the form of applets or scripts. This simplifies clients by reducing the number of features required to be pre-implemented.

Identify Object Model

The very first step in designing a REST API based application is – identifying the objects which will be presented as resources.

For a network based application, object modeling is pretty much simpler. There can be many things such as devices, managed entities, routers, modems etc. For simplicity sake, we will consider only two resources i.e.

  • Devices
  • Configurations

Here configuration is sub-resource of a device. A device can have many configuration options.

Handle errors with HTTP status codes

You need to understand that it is hard to work with an API that ignores error handling. Returning the wrong status codes, or returning a stack trace without a helpful message highlighting the error does not help the user of the API. It does not matter if you have documentation or not.

Return error details in the response body

When an API server handles an error, it is convenient (and recommended!) to return error details in the JSON body to help users with debugging. Special kudos if you include which fields were affected by the error!

{
    "error": "Invalid payoad.",
    "detail": {
        "surname": "This field is required."
    }
}

Provide pagination, sorting and filtering

This is a no brainer. Your application will likely have a huge repository of information. I do not want to call your endpoints to get all fruits and have 100,000 fruits sent to me at the same time. You do not want to do that even. The overload on your server will be crazy and you will burn up your resources rapidly.

Also, I want a way to select only fruits that say fall into the citrus family or fruits that are found in a specific country. I also want to sort them either alphabetically or by some other sorting method you have. These are the little things that will improve how I use your API.

Basics about API security

RESTful APIs have few security considerations, but that does not mean we should ignore security completely. We will approach API security from two perspectives: authentication and authorization.

Authentication

This has to do with verifying the identity of the person trying to access your API. This can be done through multiple ways. At the simplest form, this is providing a username/email and password combination. For APIs, it will most likely involve using a security token which will identify a user. More complex scenarios will have key/secret pairs often used to integrate one application into another.

Authorization

This answers the question of “What can you do”, indicating it comes after authentication. Authorization comes in handy when you are designing endpoints for accessing data that is either very specific to a particular person or sensitive information only a predefined set of people can access.

Open API Initiative

The Open API Initiative was created by an industry consortium to standardize REST API descriptions across vendors. As part of this initiative, the Swagger 2.0 specification was renamed the OpenAPI Specification (OAS) and brought under the Open API Initiative.

You may want to adopt OpenAPI for your web APIs. Some points to consider:

  • The OpenAPI Specification comes with a set of opinionated guidelines on how a REST API should be designed. That has advantages for interoperability, but requires more care when designing your API to conform to the specification.

OpenAPI promotes a contract-first approach, rather than an implementation-first approach. Contract-first means you design the API contract (the interface) first and then write code that implements the contract.

Further reading