Introduction to REST APIs

What’s a API?

An API is an application programming interface. It is a set of rules that allow programs to talk to each other. The developer creates the API on the server and allows the client to talk to it.

REST determines how the API looks like. It stands for “Representational State Transfer”. It is a set of rules that developers follow when they create their API. One of these rules states that you should be able to get a piece of data (called a resource) when you link to a specific URL.

Each URL is called a request while the data sent back to you is called a response.

The Anatomy Of A Request

1. Endpoint
2. Method
3. Headers
4. Body (Data)

Endpoint Consensus

Consider the following endpoints:

• /user/user1
• /user/id/user1
• /user/?id=user1

All are valid options to fetch data for user user1. The number of combinations increase further when you have more complex operations. For example, return ten users whose surnames start with ‘A’ and work for companyX starting at record 51 when ordered by date of birth in reverse chronological order.

API Versioning

API changes are inevitable, but endpoint URLs should never be invalidated when they’re being used internally and/or by third-party applications.

APIs are often versioned to avoid compatibility issues — such as /1.0/user/user1 supersedes /user/user1 — but the old endpoint remains active. However, this increases the workload, as multiple APIs are maintained. Older APIs can eventually be scrapped, but the process requires careful planning.

Authentication

The Joke API shown above is open: any system can fetch a joke without authorization. This is not viable for APIs which access private data or permit update and delete requests.

Client-side applications on the same domain as the RESTful API will send and receive cookies just like any other HTTP request. (Note that Fetch() in older browsers requires the credentials init option to be set.) An API request can therefore be validated to ensure a user is logged in and has appropriate rights.

1. HTTP basic authentication. An HTTP Authorization header containing a base64-encoded username:password string is passed in the request header.
2. API keys. A third-party application is granted permission to use an API by issuing a key which may have specific rights or be restricted to a particular domain. The key is passed in every request in the HTTP header or on the querystring.
3. OAuth. A token is obtained before any request can be made by sending a client ID and possibly a client secret to an OAuth server. The OAuth token is then sent with each API request until it expires.
4. JSON Web Tokens (JWT). Digitally-signed authentication tokens are securely transmitted in both the request and response header.