What is an API?

The acronym API stands for “Application Programming Interface”. 

Sounds fancy, doesn’t it?

But what is an “Application Programming Interface”?

A definition of “Application Programming Interface (API)” is, “an interface or protocol between different parts of an application”. 

A shorter definition would be, “How parts of an application talk to each other”.

Let’s look at the “parts” of basic web  application.

In our basic web  application, there are two distinct parts:

A Website

A Database

Diagram displaying the two parts of the web application: the web site and a database that store  products data.

Sometimes, applications talk directly to a database. 

Other times, it’s just not a good idea to talk directly to the database. 

The web application is a website that runs in a browser. 

Databases require secure connection information. 

You don’t want to put secure connection information in the browser where anyone can see it.

A better idea would be to put all of the database connection code into a separate part of the application. 

This part connects securely to the database, but keeps your secret connection information safe and sound.

 Instead of talking to the database, the website talks to this new part of the application. This new part is the “API”.

An API call from an web site or mobile app reach an API endpoint that connects to a back end business logic application, such as message processing or user management application, which can then read or write data into a repository or a database.

APIs


An Application Programming Interface, or API, is a protocol for communication between different web applications or different components of the same application. These different components will want to share information with each other or perform actions on other spaces, and APIs allow for this interaction. It is useful, then, to have a standard language for how this communication will occur.


JSON


One such language is Javascript Object Notation (JSON), which is a simple way of representing information in human- and computer-readable way so that it can be passed between parts of web application.

JSON example:

  {

      “origin” : {

          “city”: “Tokyo”,

          “code”: “HND”

      },

      “destination”: {

          “city”: “Shanghai”,

          “code”: “PVG”

      },

      “duration” : 185,

      “passengers” : [“Alice”, “Bob”]

  }

  • The curly braces enclose a JSON object.
  • The contents of the JSON object are divided into key-value pairs.
  • origin and duration are themselves JSON objects, which are nested in a hierarchical structure.
  • passengers shows how lists can be values.

interaction between APIs happens through URLS, which specifics which particular information that should be accessed.


HTTP Methods


HTTP request method used depends to the type of action that should be performed.


Common HTTP methods are:


GET : retrieve a resource
POST : create a new resource
PUT : replace a resource
PATCH : update a resource
DELETE : delete a resource

What is REST?

Representational State Transfer, or REST, is an architectural pattern that provides guidance on how to name and structure endpoints in an API. 

There are a lot of fancy ideas behind REST, but you only need to understand two:

Action defined by HTTP request method

Organization by resource

Action defined by HTTP request method

When you load a web page in the browser, the browser makes an HTTP request. 

That request is called a “GET”. It’s just that the browser does that automatically. 

All you ever see is the URL and the page that gets returned.

Diagram showing an HTTP request from the browser to the server and the response returning HTML.

When you’re calling an API, you can control the method that is used to call a URL. 

The method is called, wait for it, the “HTTP request method”. 

In a REST architecture, these HTTP request methods are used to define the action that you want to take on a resource. 

REST says that HTTP request methods match up to what a service does.

ACTION DEFINED BY HTTP REQUEST METHOD

Service Action HTTP Request Method

Create something POST

Retrieve something GET

Update something PUT

Delete something DELETE

A service that returns a set of records from a database should listen for a GET request. 

When a service’s job is to delete a record, the service should listen for the DELETE request method. You get the idea.

Sometimes people will refer to HTTP request methods as “verbs” or “HTTP verbs”. It’s a slightly cooler-sounding way of saying the same thing.

Organization by resource

The second concept is called “Organization by resource”. 

The URLs for your services should closely match the resources that they’re managing. 

For example, if you have a service that retrieves all of the products in a database, then you would call that endpoint, “products”.

HTTP

http://127.0.0.1:7071/api/products

The fact that “products” is plural indicates that it returns multiple results. If you are getting only one product, you would call a “product” endpoint and pass the ID if the item you want as part of the route.

HTTP

http://127.0.0.1/api/product/1