What is an API?

In simple terms, API (Application Programming Interface) is a mechanism that enables two software to communicate with each other. For example, when a user clicks on a product on Amazon's website, the frontend of the website sends a query to Amazon's server requesting information about that product. The server then queries its database for the relevant data, and if it exists, it sends the information back to the frontend via API. So, API works like a bridge between applications to share data between them.

Types of API Architecture

REST (Representational state transfer), RPC (Remote Procedure Call) and GraphQL are widely used API architectures out there.

REST

REST API should use noun-based URLs meaning. To get all the users, rather than using verbs like `https://example.com/api/getStudents` it should use nouns `https://example.com/api/students`. Also, it should follow RESTful conventions for URL patterns, such as using plural nouns for collections and singular nouns for resources.
It should use HTTP methods (GET, POST, PUT, DELETE, etc.) for CRUD (Create, Read, Update, Delete ) operations appropriately and according to its intended purpose. For example, GET for retrieving data, POST for creating data, PUT for updating data, and DELETE for deleting data.
REST APIs typically return JSON or XML data. As for our example URL, https://example.com/api/students should return all the students in the collection. Although you can use techniques like pagination to limit the number of users you are returning.
To get a specific entity ( like a specific user from a users collection ) you can specify the identifier for this specific user. For example, making a get request here `https://example.com/api/students/2012020302` should return only one entity.
To get sub-resources you can use `https://example.com/api/users/2012020302/hobbies/hobby-1`
For non-CRUD operations like search can be done with the query parameter where you pass a query with your endpoint. For example, `https:/example.com/api/students?name=Alex` should return {"name": "Alex", "studentId":2012020302, ...}

RPC

RPC (Remote Procedure Call) is another type of API. It allows a program to call a function on another program running on a different machine as if it were a local function call.

With RPC, the program that calls the function is known as the client, and the program that provides the function is known as the server. The client sends a request to the server with the name of the function and any arguments needed. The server then executes the function and sends the result back to the client.

RPC APIs have a different URL convention compared to REST APIs. Instead of using noun-based URLs, RPC APIs use verb-based URLs.
This means that an endpoint like `https://example.com/api/getStudents` would be used to call a function called `getStudents()` on a server.
Also, unlike REST APIs, RPC APIs typically use only the POST HTTP method for all operations.
The payload of the POST request usually includes the function name and its arguments in a structured data object like JSON or XML. Similarly, the response from an RPC API call also typically includes a structured data object like JSON or XML
RPCs can also include error codes and messages to communicate any errors that may have occurred during the function call.

GraphQL

GraphQL APIs use a single endpoint and the HTTP POST method to send requests.
The client sends a query in the request body, and the server responds with only the data requested in the query.
GraphQL APIs have a schema that defines the types of data available in the API and how they can be queried, written in the GraphQL Schema Definition Language (SDL).
Clients can specify exactly what data they need, including nested fields and relationships, reducing the need for multiple requests as in REST APIs.
The example below demonstrates how to retrieve data for a user with a specified ID, including their name and email:

1query {
2  user(id: "123") {
3    name
4    email
5  }
6}

The API would respond with a JSON object that looks something like this:

1{
2  "data": {
3    "user": {
4      "name": "John Doe",
5      "email": "johndoe@example.com",
6    }
7  }
8}