Application Programming Interface (API)

An API stands for application programming Interface, which is a fancy way of referring to software that can interact, or communicate, with other software to perform an action.

For example:

If you were to create a new account, or login, to a website, that website is most likely sending data, or communicating, with a with a server which is also interacting with a database.

In this case the website, server and databases are all APIs because they are different softwares that are communicating with each other to perform an action. However, an API can also refer to the individual functions that interact and run within a single application, such as a website.

The Architecture of APIs

All APIs follow a basic structure of two parts: the client side and the server side:

Client Side

The client is the application that sends the request to initiate the execution of an action.

Server Side

The server side refers to the application that receives the request and returns a response.

In our example case of logging in to a website, the website is now the client sending a request to a server. The server is, well, the server side of this interaction and will send a response that determines if the login information was correct.

Not All Server Side Interactions Are Servers

However, as stated before APIs can also be functions within an application. You don't necessarily need an actual server to have a server side interaction with an API.

As another example, a website may have a function that performs an animation, but calls on another function to determine the timing of said animation. Now we have two software code that are communicating with each other to perform an action: the first function being the client and the second the server.

REST APIs

A REST API is the most popular API architecture style for web, and stands for representational state transfer. Applications that follow the REST architecture are called RESTful APIs.

REST APIs use the Hypertext Transfer Protocol, HTTP for short, which is a set of instructions we use to transfer files and data over the web. HTTP has four main methods that helps us Create, Read, Update, and Delete data: often called CRUD operations.

REST Functions

HTTP POST Method

The POST method is used to Create ( CRUD ) a new resource. Resources are the information, or groups of information, that we use to run applications. A database would be considered a collection of different resources, such as a table list of users, and a particular user stored on that list would be a single resource.

HTTP GET Method

The GET method is used to retrieve/read ( CRUD ) the data of a resource. Think of visiting a user's profile in a given website. The backend, non-visual code that handles logic, of that website is retrieving that users data for display purposes.

HTTP PUT Method

The PUT method is used to update ( CRUD ) an existing resource. If that resource doesn't exist it may create a new one, or return an error. If a user were to update their profile information, the backend would send a request to the database to perform the update with the new values.

HTTP DELETE Method

The DELETE method is used to delete ( CRUD ) an existing resource. This is self explanatory.

Routes and Endpoints

To access the different methods of a REST API we use URL routes with HTTP methods to match to a specific endpoint on the server.

An endpoint is just a function that is defined with a URL and HTTP Method to perform an action. A server waits for requests to that endpoint to perform the required action. For example:

Suppose we had a web application with a base url of https://random-example-url.com

If a user wanted to view a list of all users in that application, we might define an endpoint in the server using the GET method with the following path:

https://random-example-url.com/**users**

Once a user visits that url the server will know to use that path with the get method retrieve a list of all users.

However, if we wanted to view a specific users information we might use this path

https://random-example-url.com/users/**:UserID**

The colon ( : ) placed before UserID denotes that it is not a literal path, but a dynamic path with UserID as a variable. It will change depending on the specific user we choose to view. for example if we had a user named Jane Doe with an id of 3 the path would be:

https://random-example-url.com/users/**3**

Furthermore, because endpoints also require a method to define when it is triggered, the same url can have multiple endpoints on the server:

GET - https://random-example-url.com/users/3 - to retrieve that users data

PUT - https://random-example-url.com/users/3 - to update that users data

DELETE - https://random-example-url.com/users/3 - to delete that users data

A developer will match specific actions performed by the user to the appropriate endpoint on the server so it will know what actions to perform. For example:

If Jane Doe wanted to delete their own profile they might click a button to do so. That button will trigger a function to send a request to https://random-example-url.com/users/**3** with the delete method so the server will know to use the Delete endpoint function of that url. Not the GET or PUT endpoints.