Part 1: API explained
This is the first part of series about API Testing. I am going to start with general concepts, I will talk about fundamental concept of APIs, tracing their historical roots, exploring various types of protocols they employ, and understanding the essential components that constitute an API.
A Historical Perspective
Back in the 1950s, an API was understood as a potential method to facilitate communication between two computers. This term was first mentioned in a 1951 book written by Maurice Wilkes and David Wheeler called ‘The Preparation of Programs for an Electronic Digital Computer’. It outlined several key computing terms, including the first API. At this stage, an API was starting to exist, but they were limited to simple, command-line interfaces that enabled programmers to interact with computers.
Blog: https://blog.postman.com/intro-to-apis-history-of-apis/
What is API?
API is an Application Programming Interface. API is a set of routines, protocols and tools for building Software Application.
How API evolved throughout the time?
Throughout the time the internet has changed and evolved, applications and APIs evolved along with it. Many years ago APIs were built with strict rules to allow the two sides of the interface talking to each other. Over time, different API protocols have been released, each of them has its own pattern of standardizing data exchange.
- SOAP is an XML-formatted, highly standardized web communication protocol. Released by Microsoft in the 1990s. XML data format drags behind a lot of formality. Paired with the massive message structure, it makes SOAP the most verbose API style.
- In the early 2000s, the web started to shift towards a more consumer-based place. Some e-commerce sites, such as eBay and Amazon, started using APIs, which are more public and flexible. Twitter, Facebook and others joined them as well in using REST APIs.
This API style was originally described in 2000 by Roy Fielding in his doctoral dissertation.
REST is the Representational State Transfer Protocol. REST makes server-side data available representing it in simple formats, often JSON. It is the most commonly used protocol nowadays.
3. The internet continued to change, mobile applications were becoming popular. Companies faced challenges with the amount of data they wanted to transfer on mobile devices. So, Facebook created GraphQL. This query language helps to reduce the amount of data that gets transferred while introducing a slightly more rigid structure to the API.
4. gRPC was developed by Google for implementing distributed software systems that need to run fast on a massive scale. Initially, it was not standardized to be used as a generic framework as it was closely tied to Google’s internal infrastructure. In 2015 Google liberalized it as open source and standardized it for community use, under the name gRPC. During the first year of its launch, it was adopted by large companies such as Netflix, Docker or Cisco among others.
REST API vs. SOAP vs. GraphQL vs. gRPC by Alex Xu: https://www.altexsoft.com/blog/soap-vs-rest-vs-graphql-vs-rpc/
More about REST API: https://blog.bytebytego.com/p/the-foundation-of-rest-api-http
What is RESTful API so popular: https://blog.bytebytego.com/p/why-is-restful-api-so-popular
API in more detail
The working principle of API is commonly expressed through the request-response communication between a client and a server. In a web API, a client is on one side of the interface and sends requests, while a server (or servers) is on the other side of the interface and responds to the request.
Since the REST API is the most popular, we are going to talk about it in detail.
These are the general steps for any REST API call:
- Client sends a request to the server. The client follows the API documentation to format the request in a way that the server understands.
- The server authenticates the client and confirms that the client has the right to make that request.
- The server receives the request and processes it internally.
- The server returns a response to the client. The response contains information that tells the client whether the request was successful. The response also includes any information that the client requested.
1 — HTTP Methods
Request methods are the actions that the client wants to perform on the server resource. The most common methods are GET, POST, PUT, DELETE, others are: UPDATE, HEAD, CONNECT, OPTIONS, TRACE, PATCH.
- GET: retrieves the information from the server
- POST: used to add a new object to the server resource.
- PUT: used to update the existing object on the server resource.
- DELETE: used to delete the object on the server resource.
More information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
2 — HTTP Headers
HTTP headers play a crucial role in how clients and servers send and receive data. They provide a structured way for these entities to communicate important metadata about the request or response. This metadata can contain various information like the type of data being sent, its length, how it’s compressed, and more.
Headers are logically grouped into three categories: request headers, response headers and general header. This can be seen in the network tab of the browser after sending the request.
Request headers are:
- Authorization: request header can be used to provide credentials that authenticate a user agent with a server, allowing access to a protected resource.
- Host: this is the domain name of the server
- Accept-Language: request HTTP header indicates the natural language and locale that the client prefers.
- Accept-Encoding: request HTTP header indicates the content encoding (usually a compression algorithm) that the client can understand.
- Content-Type: this field tells the client the format of the data it’s receiving
Response headers:
- Expires: this header contains the date/time after which the response is considered expired.
- Content-Length: this field in the request or response header plays a crucial role in data transfer. It specifically indicates the size of the body of the request or response in bytes. This helps the receiver understand when the current message ends and potentially prepare for the next one, especially in cases where multiple HTTP messages are being sent over the same connection.
- Content-Type: this field tells the client the format of the data it’s receiving
- Cache-Control: HTTP header field holds directives (instructions) — in both requests and responses — that control caching in browsers and shared caches (e.g. Proxies, CDNs)
- Date: HTTP header contains the date and time at which the message originated.
- Keep-Alive: general header allows the sender to hint about how the connection may be used to set a timeout and a maximum amount of request
General Headers:
- Request URL
- Request Method
- Status Code
- Remote Address
- Connection
More information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
3 — Request/Response Payload
Request Body has a format to be followed, which is understood by the server resource or the service endpoint. Usually the response body is in JSON.
What is JSON?
JSON (JavaScript Object Notation) is an open-standard file format or data interchange format that uses human-readable text to transmit data objects.
A JSON object contains data in the form of a key/value pair. The keys are strings and the values are the JSON types. Keys and values are separated by a colon. Each entry (key/value pair) is separated by a comma. The { (curly brace) represents the JSON object. An example of JSON is provided below.
{
"First name": "John",
"Age": 22,
"isMaried": false,
"Hobbies": [
"Netflix",
"mountain biking"
]
}
4 — URL
A REST API is accessed with a URL. The URL consists of a base URL, resource, path variables and query parameters. The base URL is the internet host name for the REST API. Resources are presented as sets of endpoints grouped on the basis of related data or the object they allow working with.
Difference between query parameters and path variables:
5 — HTTP Status Codes
The REST responses includes a status code that indicates whether the request was successful, and if not, the type of the error that occurred.
Response codes are grouped in various classes based on the characteristics of the response. The most common groupings are as follows (with several examples):
- Informational — 1XX
100 — Continue: this interim response indicates that the client should continue the request or ignore the response if the request is already finished.
2. Success — 2XX
200 — OK: the request was successful
201 — Created: the request was successful , and one or more entities was created
204 No Content — request was processed successfully and no data returned
3. Redirection — 3XX
301 Moved Permanently — this response should include the new URI in the header so that the client will know where to point the request next time
304 — Not modified
4. Client Error — 4XX
400 — Bad Request: the request was not properly formed therefore was not successful
404 — Not Found: the URI path is incorrect, or communication with the server was unsuccessful
403 Forbidden — the client has the appropriate authentication to make the request but doesn’t have the permission to view the resource
5. Server Error — 5XX
503 — Service Unavailable: the responding server is temporarily down for some reason.
More information: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
Conclusion
We began by diving into the fundamental concepts, grasping the essence of Application Programming Interfaces.
Tracing their historical roots, we witnessed the evolutionary growth of APIs. From the early days of monolithic architectures to the rise of microservices, APIs have proven to be the backbone of seamless communication between various software components.
Furthermore, we explored the diverse types of protocols employed by APIs, including REST, SOAP, GraphQL, and more. Each protocol brings its unique strengths, ensuring that developers have the flexibility to choose the most suitable option for their projects.
Understanding the essential components of an API, such as endpoints, methods, headers, and payloads, has given us a deeper appreciation for the intricacies involved in API design and usage. These components act as the building blocks that facilitate data exchange, functionality integration, and ultimately, the seamless flow of information between different applications.
In the upcoming parts of this series, we will take a look at the world of API Testing. We will explore the best practices for testing APIs, the tools and frameworks available, and various testing methodologies to ensure the robustness, security, and efficiency of APIs.
