An Introduction to Rest APIs
Tags: api, webdev, beginners, rest
Published: 2022-12-28 19:59:05

I know in my last post I said the internet doesn't need another explanation of REST APIs, but that's exactly what I'm writing about today because, well, they're important. 🙃 

Below we'll be discussing concepts such as REST, APIs, and how they come together to create RESTful APIs.  

## **What is an API?**

API stands for Application Programming Interface, which is a set of rules two software programs use to communicate with each other and exchange data.

**Let's use an everyday example:** 

Imagine you went to the hottest 🍕pizza🍕 place in town for dinner. Upon getting there, the waiter takes your order and delivers it to the kitchen. The kitchen makes your pizza and gives it to the waiter, who delivers it back to you. All of this happens without you ever having to step foot in the kitchen or talk to the chef. An API does the same by taking your request, telling the server what you want, and giving a response back to you.

Similar to how waiters act as an in-between for guests and the kitchen, APIs process data transfer between servers and an application. 

## **How APIs actually work:**

### **Step 1** 💡 
A client application makes an API call (aka a request) to an **endpoint** to retrieve information. 

An endpoint contains a Uniform Resource Identifier (URI)   indicating where and how to find the resource on the Internet. The most common type of [URI ](https://www.abstractapi.com/api-glossary/uri)is a Unique Resource Location (URL), serving as a complete web address.
URI's include a request verb, headers, and a body. 

**Headers** store information relevant to both the client and server. Headers provide important authentication data — such as an API key, the name or IP address of the computer where the server is installed, and information about the response format.

A **body** gives additional information to the server. For instance, it may be a piece of data you want to add or replace.

When making a request, most APIs use **HTTP** verbs. 

**What is HTTP?**

HTTP (Hypertext Transfer Protocol) is a standard way of transmitting data over the web that defines how messages are formatted and transmitted, and what actions web servers and clients should take in response to various commands. It is a request-response protocol, meaning that a client sends a request to a server and the server returns a response.

**What are HTTP Verbs and Why do APIs use them?**

HTTP uses a set of standard verbs to specify the intended action to be performed on a resource. These include **GET**, **POST**, **PUT**, and **DELETE**. The acronym **CRUD** also describes what kind of requests we can send in relation to HTTP verbs:

![CRUD VERBS](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qwjglnsntbr2jqxhd1dp.png)

**HTTP Status Codes**

HTTP also defines a set of status codes that are used to indicate the result of a request. For example, a status code of 200 OK indicates that the request was successful, while a code of 404 Not Found indicates that the requested resource could not be found.

Although developers often make use of HTTP verbs to provide a standard way of interacting with resources over the web, it is important to note that APIs and HTTP verbs are _not_ the same things. APIs can use different methods of communication besides HTTP.

### **Step 2** 💡 
After receiving the request, the API makes a call to the web server. 

![API Request Diagram](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/3kqalssoqqoqmp0lhbnd.png) 

### **Step 3** 💡 
The server sends a response to the API with the requested information. The response also includes an HTTP status code.

### **Step 4**💡 
The API transfers the data to the initial requesting application.

![Infographic about API Calls](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/mqb960i1crndm87218xe.png)

## **What is REST?**

As the use of APIs became more common, protocols and sets of rules were created to provide users with defined rules that specify accepted data types and commands. These include SOAP (Simple Object Access Protocol), XML-RPC, but the one we care about in _this_ post is REST. 

**REST** stands for **Representational State Transfer**, and is a set of Web API architecture principles. To be a REST API (also known as a RESTful API), the API must adhere to certain architectural constraints. 

**TLDR** - REST is a standard that APIs follow, but there are other ways APIs can work. 

## ⭐ **RESTful APIs: How it all comes together**⭐ 

To recap, we know REST isn’t linked to any particular technology or platform. Instead, it introduces constraints that describe how the server processes requests and responds to them. 

To be considered RESTful, an API must adhere to the following constraints:

### **Client-server autonomy**

With REST APIs, the client and server work independently and use different tech stacks. The server has no idea what you're seeing as a user, and the client doesn't know anything about the server. Having this separation means the API providers and consumers can be modified without interrupting communication. 

**Why is this good?**

Easy modifiability, better system reliability. 

### **Uniform interface**

A uniform interface dictates a standardized way to communicate with a given server, no matter the client app or device that runs it. This includes having a unique identifier (URI) assigned to each resource, self-descriptive messages explaining how to interpret them and what to do next, and the ability to manipulate a resource through its representation in JSON or XML.

**Why is this good?**

Easier to use and understand.

### **Layered architecture**

The client does not need to know the details of the server implementation, as the communication between the client and server takes place over a uniform interface. When calling a server, a client doesn’t know whether there are any intermediaries along the way. This allows us to place a proxy or load balancer between the client and server, which improves scalability. Adding security as a separate layer also enhances system safety. Although these services are involved in producing the response, the client doesn’t have to worry about what’s behind the interface.

**Why is this good?**

Better for overall scaling and security.

### **Caching**

With REST APIs, we can allow clients to store frequently accessed data on their side instead of requesting them again and again. As a result, the app makes fewer calls, which reduces the load on the server and its latency. This allows the application becomes more responsive and reliable.

**Why is this good?**

Low server latency, increase in app speed and responsiveness.

### **Code on demand (CoD)**

The server can send code to the client to be executed, allowing the server to adapt to the needs of the client on the fly.

**Why is this good?**

Feature customization, extended functionality.

### **Stateless interactions**

The server does not store any state about the client sessions, so each request from a client must contain all the information necessary to understand the request.

**Why is this good?**

Enhanced performance, and app reliability.


## **Summary**
- API stands for Application Programming Interface, which is a set of rules two software programs use to communicate with each other and exchange data.
- APIs use HTTP Protocol when making requests.
- HTTP (Hypertext Transfer Protocol) is a standard way of transmitting data over the web that defines how messages are formatted and transmitted, and what actions web servers and clients should take in response to various commands.
- REST stands for Representational State Transfer, and is a set of Web API architecture principles.
- To be considered RESTFUL, APIs must adhere to these constraints:
  - Client-server architecture
  - Statelessness
  - Cacheability
  - Layered system
  - Code on demand 

I'm hoping to write a follow-up post with an API tutorial but until then, here are some APIs with great documentation: 

- [Stripe](https://stripe.com/docs/api)
- [Twilio](https://www.twilio.com)