10 Must Know Concepts When Working with APIs

1. Endpoints

The endpoints indicate where the resources are located. When an API interacts with another system, the touchpoints of this communication are considered endpoints.

For APIs, an endpoint can include a URL of a service. The endpoint shows the end path of a resource URL only, not the base path common to all endpoints.

e.g.

URL

https://example.com/some/sample/endpoint

Endpoint

/some/sample/endpoint

2. Request Parameters

Parameters are options you can pass with the endpoint. Parameters are used for specifying the response format, the amount of results returned or filtering options.

There could be path parameters or query string parameters sent along with the endpoint information.

Path parameters appear within the path of the endpoint, before the query string (?). They are usually set off within curly braces.

e.g.

cars/{carId}/drivers/{driverId}

In the above example carID and driverID are path parameters.

Query string parameters appear after the query string (?) in an endpoint.

e.g.

/notes?offset=100&limit=50

In the above example offset and limit are query string parameters.

3. Header parameters

Request parameters that are included in the request header are called header parameters. Usually header parameters are related to authorization.

e.g.

Authorization: Bearer GgXaz19RDv23jAIrQRDv23jy2KsJMy2KsJM8

x-api-key: RDv23jy2KsJM8

4. Data Representation

A resource is an entity with associate data and state. A resource can be represented in multiple formats, such as JSON, XML, YAML etc.

The data stored within a resource could be sent back and forth using any representation when you invoke APIs.

The most common representation we use today is JavaScript Object Notation (JSON). It is a lightweight syntax containing objects and arrays, usually used (instead of XML) to return information from a REST API.

5. REST API

REST stands for Representational State Transfer. REST uses HTTP protocol to make requests and provide responses in a language agnostic way. Developers can choose whatever programming language they want to make the calls.

REST is stateless, meaning that the server does not store any state about the client session on the server side. You are using a “representation” of a resource to transfer resource state which lives on the server into application state on the client. Client is responsible for storing and handling all application state related information on client side.

6. Content Negotiation

When client and server is interacting, both parties need to have a common understanding on which representation to use for request and response.

Content negotiation is the mechanism that is used for serving different representations of a resource at the same URL.

API consumer can specify which is best suited for the client, for example, JSON or XML. When the content type is agreed upon between client and server, data will be embedded into request and response using the agreed upon content representation.

7. CORS

Cross-Origin Resource Sharing (CORS) is a mechanism that uses additional HTTP headers to tell API consuming client programs to give a web application running at one origin, access to selected resources from a different origin.

The origin here means where a request originates from. HTTP header named “Origin” is used to deal with this scenario.

A web application executes a cross-origin HTTP request when it requests a resource that has a different origin (domain, protocol, or port) from its own.

8. Caching

When it comes to client & server interaction, most of the API calls are read only requests. For such requests, we can use cashing where we store copies of frequently accessed data in several places along the request-response path.

When a consumer requests a resource representation, the request could go through one or more caches. If any of the caches along the request path has a fresh copy of the requested representation, it uses that copy to respond. If none of the caches can satisfy the request, the request will be received by the API service and the response will be generated as usual.

9. Filtering

Filtering provides basic conditional queries for processing API requests. Rather than returning the whole result set form the API, filtering will return only a selected set of results based on filter parameters.

URL parameters is the easiest way to add basic filtering to REST APIs.

There are various ways to encode filtering components into URL parameters.

10. Pagination

API provider implementation will have to use database queries to access data to provide data related to resources. Some of the queries could potentially return thousands of results. If we are to load all results for sources in one go, that would put lots of stress on the API hosting server. Pagination helps to limit the number of results to help keep both the API server load and network traffic within reasonable limits.

When using pagination, you would have to specify the page number and page size and those can be sent in the request as request parameters.

e.g.

/endpoint/employees?page=0&size=20