API is the abbreviation for Application Programming Interface and is a piece of code that specifies how different software components should interact and communicate programmatically. Many are not aware that, under most modern user interfaces, dozens of requests are being sent to API servers for data. The client then processes data returned by the API server to elicit some outcome in the user interface.
For example, if you have ever searched on an aggregator website for the best deals on flights or hotel bookings, a “request” for data based on your search criteria was made (after clicking the submit button) to an API specializing in flights or bookings. After the aggregator website retrieves the data using the API, the search results are displayed to you.
The aggregator website and its associated databases did not store the data appearing in the search results. Instead, the website sent a request for data matching your search criteria to an external web service (i.e. API). The API returned the requested data to the website, and the website parsed the data and rendered the search results.
What is a REST API?
There are many kinds of APIs. Sufficiently describing all of them here would require many blog posts. For our purposes going forward, we will limit the scope of discussing APIs just to REST APIs.
REST stands for representational state transfer and is a particular kind of architectural style that APIs considered “RESTful” are constrained by and “conform to”.
REST APIs are a very common and important type of API that uses HTTP protocol for data transmission. Since this HTTP protocol is used, a REST API is considered a “web service” that deals with the interaction between client applications and API servers. Using this protocol, a client sends an HTTP request for data to an API Server and then the server sends an HTTP response with encoded data back to the client.
The HTTP protocol used by REST APIs allows for platforms and systems written in different programming languages to interact with one another. For example, a client application written in C# can interact with an API server written in Java. This interoperability between systems makes web services very popular in modern software development, and REST APIs in particular.
REST API Use Cases
REST’s separation of concerns for the client and server makes it attractive for many kinds of projects, whether mobile development, web development, etc.
Here are common use cases:
- Cloud applications – REST’s advantage of statelessness (discussed more later) is suited well to cloud applications.
- Cloud Computing – REST supports cloud computing in controlling how URLs are decoded during client-server communication.
- Microservices – REST APIs connect microservices together into one application.
Anatomy of REST API request
The APIs set the rules for how client applications/backends and API servers can communicate programmatically. The API determines how the client needs to send requests, and what sort of information is returned by the API to the client.
The basic components of REST API requests are discussed below.
Resources
The different kinds of information the client can request from the API are called “resources”. Think of a resource as a type of data object returned by the API.
For example, the well-known Swagger Petstore API consists of several resources, namely: Pet, Store, and User.
All relate to the central theme of the pet store, but each represents the different data objects you can create, manipulate, or delete.
You will notice when reading API documentation that endpoints are grouped under their related resource. For example, the “pet” resource has several related endpoints (discussed soon) to take action on a pet resource. You can create, update, or delete Pets.
To solidify the concept of resources: When you create a Pet, know that the API returns a Pet resource or pet “object” that in some sense represents a physical pet added to the pet store’s system.
Endpoints
If you were to expand either the pet or store resource, you would see various endpoints. Each endpoint does something different.
Endpoints are at the core of API requests and usually stand out in API documentation. Most notably, the method (or action, like POST) of the request and the end path (ex. /pet) of the endpoint are highlighted. The following is a list of endpoints of the pet resource.
When you send a request to an API, you send an HTTP request using the specific “end path” of the endpoint. The end path comes after the API’s base URL. For example, the base path of the Swagger Petstore is https://petstore.swagger.io/v2/, whereas an end path for a pet store endpoint looks like /pet. The full Resource URL used to send a request is https://petstore.swagger.io/v2/pet.
An endpoint can have multiple paths and methods (discussed soon) that elicit different responses from a resource. The request below sends a request using the /pet endpoint with the POST method. POST indicates you wish to create something, in this case, a pet.
The request below sends a request using the same /pet endpoint, except this time you use the GET method to retrieve details of a pet rather than create one. Notice that you need to append the petId of the pet to your request (parameters discussed later).
Methods
As briefly discussed, HTTP methods are sent with API requests to indicate the actions you would like to take toward a resource. There are many API methods, so I will only list some important ones:
POST request – creates a resource.
GET request – retrieves information about a resource.
PUT request – updates or creates a resource.
DELETE request – deletes a resource.
HTTP methods correspond to CRUD Operations. For example, the HTTP methods POST, GET, PUT, and DELETE correspond to create, read, update, and delete CRUD operations.
Parameters
Think of parameters as options or filters passed with an endpoint that affect what information is returned in the response. There are different types of parameters, such as:
Header Parameters – Included in the Request Header of an API request and are usually related to authorization. For example, many times an access token parameter is included in the Request Header that authorizes requests of the client to the API.
Path parameters – Included in the Resource URL of an API request and are indicated by curly braces at the end of an endpoint’s end path. For example GET /pet/{petId}.
Query string parameters – Included in the Resource URL of an API request and appear after a quotation mark (?).
Note that endpoints may or may not use all of these kinds of parameters. However, header parameters are usually included for authorizing requests.
Request Body
Request bodies are essentially JSON objects passed in the body of an API request and are often used with POST or PUT methods. Even though they are not classified as such, they are like parameters that take the form of a JSON object rather than a key-value pair like a normal parameter.
REST’s Core Principles
REST’s core principles are what makes it so attractive in software development.
Client and Server
REST APIs have an architecture designed to separate the client from the server so both can evolve independently. The client is not concerned server’s data storage, and the server is not concerned with the user interface. This separation of concerns makes user interfaces very portable and server elements more scalable.
Statelessness
The statelessness restriction of REST ensures state data is only stored in the client application and not on the server. Every request made by the client is independent of any previous requests and includes all required information. Since the server stores no session-related information, the client application manages its session data.
Cacheable
When a client sends a request to a REST API, the API must indicate that the response either can or cannot be cached. Also, it must indicate how long the client can cache responses. Caching can improve availability and performance by reducing the number of API requests since the client can leverage cached data for a certain duration of time.
Top comments (0)