Everything you need to know about an API

So what exactly is an API?

An API (Application Programming Interface) is a set of functions that allows applications to access data and interact with external software components, operating systems, or microservices. To simplify, an API delivers a user response to a system and sends the system’s response back to a user. You click “add to cart;” an API tells the site you added a product to your cart; the website puts the product in your cart, and your cart is updated.

You may hear the term “microservices” come up in relation to API. These, however, are not the same. Microservices are a style of architecture that divides functionality within a web application. While API is the framework in which developers interact with a web application. Microservices can actually use API to communicate with each other.

API lets a developer make a specific “call” or “request” in order to send or receive information. This communication is done using a programming language called “JSON.” It can also be used to make a defined action such as updating or deleting data.

There are four basic request methods that can be made with API:

GET – Gathers information (Pulling all Coupon Codes)
PUT – Updates pieces of data (Updating Product pricing)
POST – Creates (Creating a new Product Category)
DELETE – (Deleting a blog post)

So What is JSON and why is it used?

JSON (JavaScript Object Notation) is used to represent data on a server. It’s fairly easy to read by humans, and easy for machines/applications to understand. This is easy to understand as it’s outputted in key/value pairs, with the key on the left, and a value on the right. Keys are a fixed object defined by the application and will remain the same as with “category.” Whereas the values will be unique, such as “Shirts.”

What is an API Request?

There are several components of an API Request in order for it to function. Let’s go over these individuals and how they can be used to build a request.

Endpoint

There are two key parts to an endpoint that are used when making an API request. One of which is the URL. It may look like a regular URL but if you plug it into a web browser, you will receive a 404 error message. The second part is the path. The path will vary depending on what you are trying to accomplish. When we put these two parts together, we get a complete endpoint

Header

Headers provide information to the client and server. Common examples of a header would be authentication credentials such as an “Auth Token” or “Client ID”. These credentials are provided to you automatically when you create an API Account. Another common header is referred to as the “Content-Type,” which informs the server about what type of content will be sent. For example, a commonly used content type is “application/JSON” which lets the server know, we are sending JSON data across.

Method

Methods are the actions taken when sending a request. Think back to the beginning when we discussed GET, PUT, POST, and DELETE. These are all API Methods.

Data

The request data, also commonly referred to as the “body,” is information that will be either sent to or returned by a server. In the previous discussion of JSON, you can see an example of API data. The body of a request will sometimes require specific information before it can be delivered. An example of this is if you are editing a single product, the Product ID will be required before any change can be made.

What about REST & SOAP APIs?

While API follows a specific set of rules that determine how programs communicate with one another. REST & SOAP define how the API is presented. Each is similar in functionality but has several key differences and uses cases.

REST stands for “Representational State Transfer” and is the set of rules that developers follow when creating an API. REST is read using JSON as we covered previously. One of these rules is that the API should be designed in a way that is easy to use and will make sense for developers. An example of not following this rule would be to have the product endpoint “prod_839” instead of just “products.” This could cause the API to be fairly unpleasant to work with.

SOAP or Simple Object Access Protocol is another design modal for web services. Instead of the typical JSON that REST API uses. SOAP uses a language known as Extensible Markup Language (XML). XML is designed to be machine- and human-readable. SOAP follows a strong standard of rules, such as messaging structure and convention for providing requests or responses.