Understanding APIs: Simplified Guide for Beginners

As you casually browse social media or use some services on the Internet, you’re probably unaware that you’re actually interacting with an API. You may have even heard about the term API and wondered what it is and what it is used for. In this simplified guide for beginners, I will try to explain APIs in the simplest way possible. And hopefully by the time you finish reading this article you will have a clear understanding of what an API is and how it works.

What is an API?

Application Programming Interfaces—or APIs—act as an intermediary between two software programs. APIs allow users to communicate with a backend system through a user interface. An interface can be described as a contract of service between two software programs which defines how the two communicate using requests and responses. APIs are integrated in most web applications and are based on the client-server model:

• The client is on one side of the interface and sends a request
• The server is on the other side of the interface and responds to the request

In simple terms, think of an API as a service that defines:

• The inputs - what requests it will accept from us
• The outputs - what kind of responses it will produce for us

Types of API calls

An API call is a request made by the client asking the API for a service or information. There are three different types of API calls—safe, idempotent, and non-idempotent API calls. To understand the difference between these three types of API calls, let’s look at an example from a book about API testing that I have read and found really helpful to understand APIs better. The book is called API Testing and Development with Postman by Dave Westerveld. I strongly recommend it if you want to explore API topics in depth. Okay, now back to the example.

Imagine there are a couple of Lego pieces on a table. The Lego pieces represent a server, while a child playing with the Lego pieces represents the API. In this imaginary situation, you’re going to be a client.

You ask the API to tell you the color of the top Lego piece. The answer you receive is that it is blue. This is an example of an API request that is safe. A safe request is one that does not change anything on the server.

Now imagine that you give the child a green brick and ask them to replace the top brick on the stack with it. After the child does that, the brick stack is changed. Now it is made up of a green, red and yellow brick.

Since the server has changed, this is not a safe request. However, if you give the child another green brick and ask them to replace the top brick again, nothing will change on the server. The stack will still be made up of three bricks with the same colors as before. This is an example of an idempotent call—API calls that return the same result no matter how many times you call them.

If you now give the child a green brick and ask them to add it to the top of the stack, it will consist of four bricks instead of three—two green bricks, one red brick and one yellow brick. If you then ask the child to add a blue brick to the stack, the server’s state will once again be changed and it will now consist of five bricks, and so on. This is an example of a non-idempotent call, which are API calls that return different results every time you call them.

Types of API requests and responses

Request methods

GET is used to retrieve a resource (information) from the server.

• It is a safe call, because nothing is added or changed on the server
• Server only looks for the data we request and sends it back to us
• In other words, GET request performs a read operation
• This is the default request method

POST is used to create a new resource on the server.

• Changes the server by creating a new entry
• The only method that is non-idempotent because every POST request results in a new object being created on the server
• In other words, POST request performs a create operation

PUT is used to update an existing resource on the server.

• Changes the server by modifying the whole resource
• It is an idempotent call because repeatedly executing the same request will have the same result as the first time
• Can be used for creating new entry, however, the repetitive request will not generate a new resource
• Namely, PUT request performs an update operation

PATCH is similar to PUT request, the difference is that it only modifies parts of the content of an existing resource.

DELETE is used to delete a resource from the server.

• It changes the server by removing an existing resource
• It is idempotent because multiple requests should result in only one thing being deleted
• Specifically, DELETE request performs a delete operation

Other, not commonly used, API request methods are:

• HEAD is similar to GET, except that it doesn’t return a response body. It is useful for API smoke testing, when we simply want to verify that a resource is available.
• OPTIONS is used to get data describing what other methods and operations the server supports at the given URL.

Note: Not every API request method is available for every endpoint, that depends on how the API is designed.

Response structure

When the server sends us a response for the given request, the main part we are usually interested in is the response body. Besides the response body containing the information we’ve requested from the server, the API response also contains:

• Status code — gives us more information about whether the request was successful or not.

• Response headers — provide hints to see what is going on when testing APIs. Common response headers are:
  • Content-Length — indicates the number of characters in the response body
  • Content-Type — indicates the format of the data in the response body (e.g. JSON)
  • Date — identifies the date when the request was processed
  • Many more often related to authentication of the user

Response status codes

Status code is also one of the most important parts we’re interested in when looking for a response from the server. There are many response status codes with different meanings which are divided into the following five categories:

• 1xx codes: Informational status codes. These are acknowledgement responses used to pass on information. They are not commonly used.
• 2xx codes: Success status codes. These status codes mean that the server has received the request and processed it successfully. Most common success codes are:
  • 200 OK: Informs the client about successful response.
  • 201 Created: Should be returned for POST requests, stating that the resource is created successfully on the server.
  • 202 Accepted: Indicates that the response is successfully received, but the processing is not yet finished.
  • 204 No Content: Informs the client that the request is successfully processed, but no content is returned. Usually used for DELETE requests.
• 3xx codes: Redirection status codes. These codes are generally used in case of URL redirection.
• 4xx codes: Client error status codes. These codes are returned if the client’s request has an error. For example, the request could be incorrect or the resource which the client is looking for doesn’t exist. Most common client error codes are:
  • 400 Bad Request: There is something wrong in the request, which is why the server cannot process it.
  • 401 Unauthorized: The client needs to be authorized to make the request.
  • 403 Forbidden: Informs the client that the request is correct, but the server refuses to process it because the client might not have required permissions.
  • 404 Not Found: Informs the client that the resource that is requested doesn’t exist.
• 5xx codes: Server error status codes. These are returned when the server fails to process the request and cannot send the correct response. Most common server error codes are:
  • 500 Internal Server Error: This is a generic status code returned when an unexpected error happens on the server while processing the request.
  • 503 Service Unavailable: Informs the client that the server is not available because it may be down for maintenance or because of another reason.

There are plenty of websites that describe all the status codes and their meanings, for example, HTTP status codes.

The structure of an API call

To summarize what we’ve learned so far, we can see that every API call consists of a request sent from client and a response received from the server. On top of that, we can see that requests and responses consist of the following:

API headers represent the metadata associated with requests and responses. They provide extra information to the server about the client that is sending the request (e.g. what format we use to send the data). Headers can be added or modified as needed for every API request. They are property-value pairs that are separated by a colon.

API body is the data (information) that we give to or receive from the server when we send API requests. The body can take many forms:

• Form data
• Encoded form data
• Raw data - most commonly used with JSON format
• Binary data - used for sending files over API
  

API response is the data we receive from the server after it finishes with processing the request we’ve sent before. When we send the API body to the server, we’re sending a request body. With the API response, we’re receiving a response body.

JSON (JavaScript Object Notation) is the most common format for sending and receiving data through an API call. It is specified with key-value pairs wrapped with double quotation marks.

{
  "property1": "value1",
  "property2": "value2",
  "property3": "value3"
}

Let’s take a close look at following example URL used for an API call, and see what it is composed of:

Base URL (https://swapi.dev/api) is defined by scheme, host and base path on the root level of API specification. It is the same for all API calls, usually with the following format: <scheme>://<host>/<basePath>

Endpoint (/people) is appended to the base URL and it specifies the resource. In other words, it is the uniform locator for a particular resource that we want to interact with on the server.

Request parameter (/1/) is used to get particular information about different objects that are all of the same type. In the API documentation it can be specified in the following formats:

• /people/:id/ (in Postman this is referred to as “Path variables”)
• /people/{{id}}/

Query parameter (?format=wookie) often acts like a kind of filter or additional action that you can apply to an endpoint. They are usually added at the end of the request URL, represented by a question mark and are specified with:

• Key - the item that you are searching for
• Value - what you want the query to return

Conclusion

APIs are a critical part of ensuring a seamless connection between two software programs and simplifies the way applications, systems, or platforms send and receive data.

Now that you know the essentials of APIs—what they are, what the different types of API calls, requests, and responses are, and what the structure of an API call looks like—it’s time to move on to API testing and further develop your knowledge of APIs.

Need help with API testing? We have a dedicated team of API experts. Contact us to learn more about our API testing services and how they can benefit your organization.