top of page
  • Writer's pictureCraig Risi

How APIs work

I initially wanted to write about API automation and how to do it, however, the more I put all my ideas down, I realised that the best way to do is probably unpack the architecture of APIs a little more to help people make more sense of them before diving into the automation topic completely The reason for this is that while automating APIs itself might actually be straightforward, it requires a greater understanding of the software architecture to test and automate effectively which I perhaps why many non-technical testers prefer to stick with frontend automation over API automation. Hopefully unpacking this in more detail will help to improve the testing efforts for your APIs.

I probably shouldn’t need to explain what an API is or why they exist, but for the sake of those who are perhaps less technically, I will explain them anyway. The term stands for “Application Programming Interface” and effectively acts as a communication channel for other services and applications to communicate with.

What this essentially allows applications to do is to communicate with each other without needing to understand the inner workings of the other or even need to be coded in the same language. APIs essentially work as translators who will receive a message in a particular format, allow the code to process it in whichever way it needs and then return a message back in a language that the initial application understands. APIs are useful not just for allowing different applications to talk to each other in a convenient and secure manner (especially if designed correctly), but also play a big part in breaking bigger systems into smaller applications that can now operate independent of each other (microservices) allow them to be more easily maintained developed and scaled for future use, without needing to affect parts that remain unchanged.  

API Protocols

While APIs can essentially come in whichever form it needs, standards have been created for best use and to ensure there is some commonality in how they work. Especially important when we consider the large number of APIs effectively in effect on any specific large integrated system on the web. Think of it as a language. In order for people to work together, they would typically need to be able to speak the same language. Protocols essentially help to ensure that everyone is speaking the same language with each other, even if their home languages are something else entirely.

Below is an example of two common APIs from Google and Facebook that essentially allow you to write code to their services, sending and receiving the information you need without needing to know the code that drives it or some of the confidential information contained by the companies too:

  • Google APIs, which allow you to connect your code to the whole range of Google services, from Maps to Translate. APIs are so important to Google that they acquired Apigee, a leading API management platform.

  • Facebook APIs, which allow you to programmatically access Facebook’s social graph and marketing tools. (The company has been restricting just what user data you can access via these APIs in the fallout from Cambridge Analytica and other scandals.)

Web Service Protocols

While APIs can take the many forms that a company desires, it does help to have some defined standards or approaches for companies to follow with their APIs. And with web services the most common form of API communication out there, it makes sense for me to focus on these more specifically. There are mainly two types of services SOAP or, REST protocols:

REST stands for REpresentational State Transfer which is new on the block as compared to SOAP which means it must overcome all the problems with SOAP. REST is a lightweight protocol which uses URL for all the needed information. It uses four HTTP methods to perform tasks:

  • GET - To get the information. For example, getting longitude and latitude in case of location mapping API.

  • POST - To insert some data in the resource.

  • PUT - To update the resource.

  • ·DELETE - To delete from the resource.

REST Advantages

REST is easier to use for the most part and is more flexible. It has the following advantages over SOAP:

•   No expensive tools required to interact with the web service

•   Smaller learning curve

•   Efficient (SOAP uses XML for all messages, REST can use smaller message formats)

•   Fast (no extensive processing required)

•   Closer to other web technologies in design philosophy

SOAP stands for Simple Object Access Protocol. It uses XML for message exchanging. All the information which is required to perform this task is given in its WSDL which is Web Service Description Language. SOAP is heavyweight due to its extensive used standards and XML. The main advantages of SOAP over Rest is that it has built-in error handling and it can be used with other protocols like SMTP.

SOAP Advantages

SOAP provides the following advantages when compared to REST:

•   Language, platform, and transport-independent (REST requires the use of HTTP)

•   Works well in distributed enterprise environments (REST assumes direct point-to-point communication)

•   Standardized

•   Provides significant pre-build extensibility in the form of the WS* standards

•   Built-in error handling

•   Automation when used with certain language products

Knowing which API protocol you are using will ultimately help determine the tools that you may use to help in your automation efforts, though regardless of the protocol you should be able to apply the same approach to the APIs at hand and build a framework for the required purpose.

What information API messages need

The API Protocol will determine not just the different messages that can be sent, but the overall format of the message and how it should look. And while SOAP is a lot less prescriptive on this, REST provides a pretty defined architecture (perhaps why it is so popular) and to provide some guidance on this I will focus on a REST message here, so you can understand what information is needed for an API needed and what it essentially looks like:

All REST messages will require the following information which are typically presented in some sort of JSON, XML or HTTP format, even if they exist in differing formats:

·        The endpoint

·        The method

·        The headers

·        The data (or body)

The endpoint (or route) is the URL you request for. It follows this structure:


The final part of an endpoint is a query parameter. Technically, query parameters are not part of the architecture, but you’ll see lots of APIs use them. Query parameters give you the option to modify your request with key-value pairs. They always begin with a question mark (?). Each parameter pair is then separated with an ampersand (&), like this:


The Method

The API lets you know what request method to use each request. In the case of REST for instance, it’s the different GET, PUT, PUT and DELETE methods mentioned earlier. So, if you wanted to get a list of users for instance from an API< the company could look like this:

GET /users/username

The Headers

Headers are used to provide information to both the client and the server. It can be used for many purposes, such as authentication and providing information about body content. You can find a list of valid headers on MDN’s HTTP Headers Reference.

HTTP Headers are property-value pairs that are separated by a colon. The example below shows a header that tells the server to expect JSON content.

"Content-Type: application/json". Missing the opening ".

The Data (Or “Body”)

The data (sometimes called “body” or “message”) contains information you want to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests.

API Responses

Much like any normal human conversation, telling something to someone is not an indication that they received your message correctly and will do what you ask. You ideally want some form of confirmation that the message was correctly received and that’s why following any message that is sent, there should be appropriate response letting the seeding request know the message was received correctly. Again, thee can be a wide number of different response code, but the below are the default status codes that most APIs will understand.  

The status code essentially indicates the status of the message that is sent:

·        200+ means the request has succeeded.

·        300+ means the request is redirected to another URL

·        400+ means an error that originates from the client has occurred

·        500+ means an error that originates from the server has occurred

Along with a response code, you will also receive a time indicating when the message as received, which is useful in determining latency between messages or the performance of code.

What is an API Endpoint?

Whereas an API is an actual message or communication channel, the endpoint is essentially the receiver that processes the code. An API can have multiple endpoints each developed for a different purpose that can process the message based on the endpoint the message is directed to.

Some of this information might have seemed rudimentary for you, but essentially becomes especially useful to you when you begin automating your APIs because to do, you will need to build the necessary messages and protocols in code and know which data and response code to assert for correct verification. 



Thanks for subscribing!

bottom of page