web API vs web server. REST API
Tags: api, restapi, beginners
Published: 2024-04-08 17:52:56

## Table of contents

1. [Terminology](#terminology)
2. [Types of architecture styles for web API](#types-of-architecture-styles-for-web-api)
3. [REST API](#rest-api)

---

When I hear a term **API**, I imagine something really vague and abstract, because other programmers describe  it like:

- "It's a waiter between a client and chef!"
- "It's a door between guest and host"

And after hearing that, we build REST API which looks like a web server, which gets request, process it and returns response in JSON. So, it was really confusing. Where is the distinction between web API and web server?

## Terminology

First of all, let's look at definition:

> An **API** is a set of features and rules that exist inside a software program enabling interaction with it. The API can be seen as a simple contract (the interface) between the application offering it and other items, such as third-party software or hardware.

Oh, wow, really broad term. Let's narrow it to only web:

> A **web API** is an application programming interface (API) for either a web server or a web browser. A server-side web API consists of one or more publicly exposed endpoints to a defined request–response message system, typically expressed in JSON or XML by means of an HTTP-based web server.

Alright, so we construct API on the server-side for it to respond to client requests. And API specification tells how to construct request to get data from the API.

For example, we are making web application and divide front-end functionality from back-end functionality. So, for our back-end side we create API to send data to front-end on request.

## Types of architecture styles for web API

- REST
- SOAP (Simple Object Access Protocol):
  - XML-formatted structure standardized by W3C, 
  - relies on application layer protocols, most often HTTP,
  - The server maintains state by storing all previous messages exchanged with a client
- GraphQL (Graph Query Language,):
  - good for large, complex, and interrelated data sources,
  - flexible data structure defined by the client,
  - has a single URL endpoint
- Websockets:
  - a computer communications protocol,
  - bi-directional connection over a single TCP connection,
  - provide real-time data transmission

## REST API
The most popular API architecture style is still REST (Representational State Transfer). It's widely used for public APIs.

### Key principles

#### Uniform interface

- The interface must uniquely identify each resource involved in the interaction between the client and the server.
- The resources should have uniform representations in the server response.
- Self-descriptive messages – Each resource representation should carry enough information to describe how to process the message.
- The client should have only the initial URI of the application. The client application should dynamically drive all other resources and interactions with the use of hyperlinks.

#### Client/Server
The client-server design pattern enforces the separation of concerns. By separating the user interface concerns (client) from the data storage concerns (server), we improve the portability of the user interface across multiple platforms and improve scalability by simplifying the server components.

#### Stateless
Every request from client is treated independently. It must contain all of the information necessary to understand and complete the request.

The server cannot take advantage of any previously stored context information on the server.

#### Cacheability
Response should contain information about if it can be cached.

If the response is cacheable, the client application gets the right to reuse the response data later for equivalent requests and a specified period.

#### Layered System
The layered system style allows an architecture to be composed of hierarchical layers by constraining component behavior. In a layered system, each component cannot see beyond the immediate layer they are interacting with.

For example, MVC pattern. The MVC pattern allows for a clear separation of concerns, making it easier to develop, maintain, and scale the application.


#### Code on Demand
REST APIs usually send static resources, but in certain cases, responses can also contain executable code (such as Java applets). In these cases, the code should only run on-demand.