1
Application Programming Interface
What is an API?
API – Application Programming Interface is translated as Application Programming
Interface. Moreover, in this context, the word “application” refers to any software product.
Wikipedia defines the word Interface: a boundary between two functional objects, the
requirements for which are defined by a standard; a set of means, methods and rules of
interaction (management, control, etc.) between system elements.
In the physical world, the steering wheel is the interface between the driver and the
wheelbase, the remote control is the interface between the person and the TV, and the
headphone wire is the interface between the headphones and the computer. We also
constantly use another interface – UI (User Interface), that is, the interface between a
person (user) and software.
API is a contract between two applications. This contract defines how applications
communicate with each other using requests and responses. The API documentation
contains information about how developers should structure these requests and responses.
Contract, agreement, set of rules of
communication
Applications can be written in different languages (Java, PHP, Python, etc.), but they will
communicate with each other via API and will understand each other.
It’s like the rules in sports – you don’t need to know your chess partner’s language, it’s
enough that you stick to the same rules to play the game.
API is a set of such rules.
For example, a developer wrote an application in Java and made an API for it. This is a
remote control that other applications can use. Let’s imagine that this is an application
(service) that makes payments, then the service API will contain a list of methods for
management:
• method for creating an order for payment
• payment cancellation method
• method for getting a list of orders
• method for obtaining order status (paid – partially paid, etc.)
There can be many methods and they can change, new methods can be added and vice
versa – some methods will no longer be used. Sometimes methods are called “handles” –
on the one hand, this is a slang expression, on the other hand, it is really like a control
handle that you can pull (“pull the payment cancellation handle” = “send a request to the
payment cancellation method”) to get a result.
That is, the application contains complex logic, integration with banks and payment
services, you cannot go into it directly – firstly, it is dangerous (you cannot give open
access), and secondly, not all services that will use this application are written in Java , so
you won’t be able to access the code directly.
2
The developer transmits the documentation for the API to those who will use this service
(for example, the developer of the front application, that is, the user interface), or other
services that will use the application without using the UI (User Interface). API methods
have strict restrictions – external services can only receive the information that the
developer allows to receive. For example, access only to payment information for one user.
API types
SOAP API
SOAP – Simple Object Access Protocol, i.e. a simple protocol for accessing objects. The
client and server exchange messages using XML. The SOAP API is not used very often,
mainly in banking applications or other applications where increased security is needed.
RPC API
Such APIs are called remote procedure call systems. The client executes a function (or
procedure) on the server and the server sends the result back to the client. gRPC API (“g”
stands for Google, this is their development) is used as a more convenient alternative to
REST. Often found in the implementation of internal communication between services of the
same product. While REST APIs are mostly useful for microservices architectures and thirdparty
applications, gRPC is often used in IoT systems, browserless applications, and
applications with multiplexed streams.
Websocket API
Websocket API – Supports two-way communication between client applications and the
server. The server can send callback messages to connected clients, which makes it more
efficient than the REST API (ws allows multiple responses to be sent per request)
REST API
These are the most popular APIs. The client sends requests to the server in the form of
data. The server uses this client input to run internal functions and returns the output back
to the client via the http protocol. In the course we will study exactly this type of API
Let’s systematize
Result:
1. Application 1 (either web or server), accesses API Application 2API via the
network using the methods of this
2. Application 2 executes the request Application 1 (if necessary, takes data from
the Database, or saves it there) and sends it through API back to Application 1.
3. Application 1 receives the response and uses it
4. The developer and owner of API is the developer of Application 2.
3
5. As testers Application 2, we verify that the API works according to
documentation
Data transfer protocol
The Internet is a vast and complex network of interconnected computers. It is based on data
transfer protocols—sets of rules that determine how information is transferred between
different computers on a network. These protocols are necessary to ensure secure
communications over the Internet, as well as efficient data transfer for various applications
such as web browsing or downloading files from remote servers.
One of the most important protocols used in modern networks is the Transmission Control
ProtocolTCP. This protocol provides a reliable connection between two devices by using
acknowledgments to confirm the successful delivery of packets sent from one computer to
another, and error checking procedures to ensure accuracy when transmitting large
amounts of information over long distances or across multiple hops on a single device.
Also among the popular protocols there is the user datagram protocol – UDP, which
provides faster but less reliable communication than TCP. UDP is more often used in video
conferencing, since data delivery is not as reliable as TCP, but very fast.
Hypertext Transfer Protocol – HTTP, controls the transmission of web pages over the
network, and is also used when transmitting data through the REST API. HTTP is also used
to transfer data to the gRPC API, but for REST the version most often used is HTTP 1.1,
and for RPC HTTP/2.
WebSocket is a bidirectional data transfer protocol (as opposed to unidirectional HTTP, in
which “a connection was opened > a request was sent > a response was received > the
connection was closed.” does not close the connection after the request, but sends multiple
responses until some trigger for closing is triggered.WebSocket
File transfer protocolsFTP also exist, which allow users to securely send files back and forth
over the network without having to have direct access rights granted by an administrator
first-hand.
This is a very short and superficial description of several protocols that are most often used
in software development, but if you want to study this topic deeper, we recommend starting
with the OSI model, and then understanding the different levels of protocols from there.
Now it only makes sense to emphasize that of those described, the TCP and UPD protocols
are at the transport level, and FTP, WebSocket and HTTP are at the application level.
Most popular protocols
• HTTP / HTTPS is a protocol for exchanging data between applications.
• SOAP (Simple Object Access Protocol) – a simple protocol for accessing
objects.
• WebSocket is an independent web protocol that allows you to create an
interactive connection between a server and a client (browser) and exchange
messages in real time. Unlike HTTP, websockets allow bidirectional
asynchronous data flow
4
As part of our study of REST API testing, we will take a closer look at HTTP
HTTP / HTTPS
A data transfer protocol is a set of rules by which devices exchange information.
HTTP HyperText Transfer Protocol – hypertext transfer protocol
HTTPS HyperText Transfer Protocol Secure – secure hypertext transfer protocol (“s” =
secure, secure)
Simple HTTP requests and responses are not encrypted and are vulnerable to various
types of attacks. HTTPS uses TLS/SSL encryption for security, so its use is becoming
more popular (and sometimes mandatory) every year.
The HTTP protocol (this term will be used further, but it is understood that we are
talking about both http and https) defines the syntax (format and data encoding) of
interservice communication.
Each HTTP request + response exchanged between applications is one HTTP
transaction.
HTTP request URL
URL (Uniform Resource Locator) is the address of a web resource.
URL shows where a web application, web page, or portion of a web page is located and
how contact them.
We also need to become familiar with the URL structure, since later we will need to
understand how we construct this path. Let’s look at this structure using the example of
searching for a course on our website using the word “API”. We will get this link:
So, first we specify the protocol (in our case it is http or https, but there may be others,
for example ws, ftp, etc.).
After this is the domain we are accessing. Most likely, these will be different addresses
of our test servers (gradebuilder.tech is the address of our “production” server; for
testing we use other, internal environments, but the part that is located after the domain
does not change when changing the domain).
After the domain is the path, or name of the method. For example, in our case, “courses”
is a GET method that returns a list of all courses.
Then “query parameters” can be indicated – after the question mark. There are
parameters for filtering, sorting, pagination (switching between pages), as well as
information parameters (that do not affect the results, for example, UTM tags for SEO).
The format of the parameters looks like pairs: key1=value1&key2=value2 &
(ampersand) as the connector of these pairs. In our example, these are two pairs:
“search=API” is the first pair, where “search” is the name of the parameter, and “API” is
the value of the parameter. And the second pair is “page=1”, where “page” is the name
5
of the parameter, and “1” is the value of the parameter. That is, in the first pair we
indicated the word to search, and in the second the page number in the search.
Another optional component of a URL is the anchor. It is singular, declared after the #
sign and is a link inside the page (in our example, the anchor does not exist, it was
made only for the lesson, but the anchor can serve as an internal hyperlink and, unlike
parameters, there will always be one inside the URL).
To study the URL, we recommend visiting the pages of different sites – news sites,
online stores – and see how the address changes.
What is REST?
REST (Representational State Transfer) means representational state transfer. REST is
an architectural style for web development. The REST architecture outlines guidelines for
communicating resource representations between clients and servers on a network.
Representativeness is a characteristic showing that the selected objects, in their content
and characteristics, correspond to the complete set of objects from which they were
selected.
What is REST API?
A REST API or RESTful API is a web API that follows the REST architecture style.
CRUD
CRUD is an acronym for four basic functions used when working with databases:
creation (create), reading (read< a i=8>), modification (update), deletion (delete ).
Why do we care about this when learning about API testing? Almost everything the API
does is stored in the database. Accordingly, most requests go to databases where
objects are stored, or retrieved from there, or deleted.
In REST API there are 4 main methods (but not the only ones) that are responsible for
these functions:
• POST — resource creation (create)
• GET — getting a resource (read)
• PUT — resource update (update)
• DELETE — deleting a resource (delete)
A little catch
We already know that the REST API has 4 main methods:
• POST – creating a resource (create)
• GET – getting a resource (read)
• PUT – resource update (update)
• DELETE – resource deletion (delete)
But in life, you may encounter the fact that using the POST method they receive a list of
resources, but do not create anything, and using the PUT method they do not change, but
create an object.
6
Now we don’t need to dive deeply into the principles of REST API design, but we need to be
prepared for the fact that the method does not do what you learned in courses or read in
articles.
In a better world
Having learned in the previous step that not everything can be implemented according to
tradition, let’s talk about what is considered a good practice when designing an API.
I propose to look at the example of an application similar to Instagram
• POST Create resource (You are posting a photo)
• GET Get resource (You are viewing a published photo or list of photos)
• PUT Update resource (You are correcting a publication with a photo)
• DELETE Delete resource (You are deleting a post with a photo)
When you send a POST request, a post with a new ID is created. When you send a PUT
request, a new ID is not created, the publication is saved again, with the same ID.
By the way, sometimes in the implementation you can see the PATCH method rather than
PUT. These are two very similar methods; they change the object, but do not change its ID
in the database. But there is a significant difference between them: PUT deletes the old
record and saves a new, corrected one, with the same ID. And PATCH changes only those
elements that we specify. And it is a less secure method, so it is used less often.
Operations with lists
• GET /myID/photo We get a list of your published photos
• GET /myID/friends/photo Get a list of photos of your friends
• GET /personID/photo Get a list of photos of a specific person
Operations with individual publications
• POST /myID/photo/ Publish the photo (the photo ID is not specified, it is
automatically generated upon publication)
• GET /myID/photo/1 View your photo with ID 1
• PUT /myID/photo/1 We change the photo (the ID of the photo is indicated,
since you need to know which photo we are changing)
• DELETE /myID/photo/1 Deleting your photo with ID 1
• GET /personID/photo/1 Viewing a photo of another person
Please note that according to the rules of good form, the plural is not used, that is, if we
need a list, we write /photo, and if we need a specific photo, then /photo/1. You can also
pay attention to this when testing the API.
When testing an API, you can check not only the compliance of the implementation with the
documentation, but also the correctness of the documentation itself, for example, make sure
that the method request does not contain unnecessary, unused parameters (find out why
they were added – it may be that they were added “for future use” , or maybe simply due to
an oversight), or that different methods use the same variable names (for example,
“postAddress” will be indicated somewhere, and “address” somewhere, and the meaning of
the variables will be the same), when naming there should be uniformity of variables.
Another example
Look at the address bar in your browser right now. She looks like this. Let’s break it down:
7
URL https://gradebuilder.tech/courses/api-qa/lessons/example/
When this link is clicked, nothing is obviously created, so let’s assume (we can check this
through DevTools, but we won’t get ahead of ourselves) that the request was sent using the
GET method. The request was sent using the “courses” method, followed by an indication
of the “api-qa” course, then a sub-request for lessons “lessons” and an indication of a
specific lesson called “example”
In the documentation, this method will look like this: GET /courses/ {course ID} / {lesson
ID} / {activity ID} /
In the documentation, curly braces indicate something that will be replaced depending on
the context, for example, the ID of a specific object.
If we want to see the entire list of courses, we will request the GET /courses method, and if
we want to see a specific course, we will call method GET /courses/api-qa/
And when the teacher edits the lesson, the method looks like PUT /courses/edit/151 (since
when editing the beauty of the URL is not very important, here it is not the name of the
lesson that is indicated, but its ID)