In this section, we’ll go through the details of Web APIs and HTTP. After all, we have to understand what we are testing. First, let’s dive into the some of the jargon surrounding the APIs: what’s an endpoint, what’s a resource, what’s a media type, what’s REST, is every Web API a REST API? It’s the same thing for a lot of people, but it’s actually not.
We do need to understand these terms because being quality assurance professionals, we should speak the same language with the developers and business analysts, and we can’t talk about Web APIs without talking the language of HTTP, the foundation of the internet itself.
Web API Concepts
What’s this Web API that we are so keen to test? Well, it’s basically an application that sits on the server and serves some content to other applications. It has many usages, and one is to act as a gateway to the database. Let’s say, your company wants to expose some data, for example, code snippets or entire repositories of code. Would your company just expose the whole database to everybody and let them do anything they like, including deleting everything? Nope.
What you can do, is setup a Web API through which people can access some of the data having restricted rights. So now, Sanket the developer can’t break the database, but can still use that data and build his own application for whatever cool business idea he has.
So, API sits on the server, and Web APIs typically use client-server architecture:
Multiple clients, such as the one on the left, can connect to a single place at the server where the API resides, and interact with it. BTW, the test that we’ll write will act as a client, an external program talking to the API and the test.
Next, is the request/response. This is simple. Request is what you send to the server, and the response is what you get back, and you do something with it:
In our tests, we’ll dig inside the responses, and inspect every aspect of that.
Next, is the endpoint. That is the last part of the URL https://github.com/olealea, the exact point where you send your request that is supposed to send back some content. That content or the file with that content is called a resource.
What is the representation or the media type of that resource? The two most common types you will see are XML and JSON. In this course, we will operate only with JSON.
Now, let’s talk about REST API.
If you search around the internet, you will find that they also live on the servere, they also serve XML or JSON, they also communicate over HTTP.
So, are they the same thing? Not exactly. For an API to be RESTful, it has to have certain features, and one of them is HATEOAS (Hypermedia As The Engine Of Application State).
The basic idea is that an API should work like a website in terms of navigation. When you come to a website homepage, you click on a link and so on – you’re browsing using links. RESTful Web APIs, among other things, should do the same and provide clients with a single base endpoint that gives them a resource with links to follow and explore the rest of the application. It has also other features, but all we care about now, is that we can send a request, and receive a response.
To put it even simpler, we will be sending some input and we’ll be getting some output that we need to verify. Both normal Web APIs and RESTful ones do just that.
HTTP Headers
Now, let’s send a request to the GitHub API, a service that serves information on public repositories that it hosts, and we’ll use the browser as the client. I’ve already typed the url: api.github.com and I have the developer console open (F12) on tab Network, and I am going to hit enter. We send the request, and we can see that we got a JSON response.
But I would like to first take a closer look at the Headers, the following metadata:
The HTTP Response Headers:
- Server header tells you about the server that you queried and here we see that GitHub isn’t really revealing much.
- Cache-Control specifies the time a resource will be considered fresh, and it helps we’re using cached data and minimized traffic.
- Content-Type or media type – json, that we will be testing quite a lot, and not just the headers, but the actual content in the body.
- ETag helps with caching.
Types of HTTP Status Codes:
HTTP status codes are groups into 5 categories depends on the purpose:
- 1xx status codes – information response
- 2xx status codes – success response
- 3xx status codes – redirection
- 4xx status codes – client errors
- 5xx status codes – server errors
HTTP 1xx Status Codes – Informational Responses
A web server responds with a 1xx HTTP status code in the response when the received request is under processing by the server and these codes are kind of acknowledgement to the client.
100 – continue. The part of the request is received and the client can continue sending the remaining request.
101 – switching protocols. When request from the client browser asks the server to switch communication protocol and the server accepts it, then it sends the HTTP status code “100 – Switching Protocols” as an acknowledgement to the request.
102 – processing. The purpose of this code is to avoid timeout errors at client side by informing the client that the server has received the request and processing it.
103 – early hints for the client browser that the server not yet started processing the requests.
HTTP 2xx Status Codes – Success responses
2xx status codes indicate that the communication is successful and the web server could process the request received from the client browser. Below are the list of 2xx HTTP codes.
200 – OK is correct response a server should return for a successful request which indicates there are no problems.
201 – Created indicates that the server completed the received request from the client and created a new resource based on the received request.
202 – Accepted is indication of the acceptance of request but the result of request processing will be known later when the actual processing takes place.
203 – Non-authoritative information – the server processed the request successfully but returns the information from another resource to the requested client
204 – No content – the server could not able to find any content for the received request.
205 – Reset content – similar to code 204, the request was processed successfully by the server but no content is returned. The difference here is that 205 code informs the client to reset the document view.
206 – Partial content – server sends part of the requested resource due to the range mentioned in the request header.
HTTP 3xx Status Codes for Redirection
Since users don’t see the original requested URL, search engines will not index the original URL instead index the final redirected URL. So 3xx status codes have more important in search engine optimization compared to other set of status codes.
300 – multiple choices – When a requested URL is pointing towards more than one resource. Check the HTTP headers or ensure the URL is pointing to only one resource so that a user agent can access the page successfully.
301 – resource moved permanently – there is a permanent redirect set to an original URL to forward the user agent to another URL.
302 – resource moved temporarily – a temporary redirect is set to an original URL
HTTP 4xx Status Codes for Client Errors
4xx-s It indicate the browser sent a wrong request with an error that can’t be processed by the web server. You need to check the browser and send the correct request again to get the proper response.
400 – Invalid Request. The web server cannot fulfill the received request because of incorrect syntax.
401 – Unauthorized Request. A user try to access the authenticated resource. The server yet to receive an authentication or received incorrect authentication. Simple example is a web page authenticated by a user id and password typically for a registered user.
402 – Payment Required. This code was created to use during an online payment is required but currently not used for that purpose. Some servers use 402 code for different purposes like to inform too many requests received from a particular IP address.
403 – Access to Resource Forbidden – a server receive a valid request but deny to respond. An example for 403 code is a registered user trying to access a restricted page.
404 – Resource Not Found is displayed when a requested resource is no more available in the server. A dev deleted the page or changed the URL without setting a 301 redirect.
HTTP 5xx Status Codes for Server Errors
5xx error codes are returned by the web server when it encounters a problem during processing of the requested resource by the client.
500 – Internal Server Error. Generally, internal server error happens due to incorrect configuration. If you are a website owner, check the server’s configuration or get in touch with your web hosting company to fix the error.
501 – Method Not Supported. When the server does not able to provide the requested resource due to unsupported or unrecognized method used in the request.
502 – Gateway Error. When a request prompts the server1 to act as a gateway or proxy to get a response from another server2 and if the server1 received an unacceptable response from the server2.
503 – Service Unavailable. When a request is received by the server at the time it is overloaded by other requests or it is under planned maintenance downtime.
504 – Gateway Timeout. When the server1 is acting as an external gateway or proxy and did not receive the response on time from the next server2 further up in the request chain which it tried to access in order to fulfill the request .
HTTP Methods
In the article so far, we only used get. When you’re browsing the internet, every time you go to the next page, your browser under the hood, sends an HTTP GET request, but there’s also POST. Posting is used to create a new resource, for example – creating a new account. Next one is DELETE, and is self-explanatory, and one more is OPTIONS, a method that is useful for your client application. When you want to talk to a Web API, but you’re not sure what all the verbs and methods you can use, you send options as if saying “Hey, what are my options when talking to you as a service?” and you should get an response telling you “Well, when talking to me, you can use get, post, delete, and a bunch of other methods.” This way, you don’t have to guess and shoot in the dark. And btw, the status code that you should receive in case of sending it options is 204 – No Content. PUT is used to update a resource. You use post to create and put to update something. The idea is if you learn how to use GET, POST and DELETE, then using all other methods is often very, very similar. Other methods: PATH, TRACE, HEAD, Non-Standard methods.
Summary
- We took a look at what Web APIs are, their purpose, which is exposing data to others, but in a safe way. We learned the terminology that surrounds the APIs. So when I say, a client sends a request to a valid endpoint, you now know that this basically means some application sent a request over HTTP to the API to get some stuff, and it used a correct web address.
- We’ve learned that the response that we get contains both metadata and the body. HTTP Status Codes are a vital part of that metadata.
- Finally, we walked through HTTP Methods that are used by the client and the Web API to communicate between each other.
Next Section: Part II - Getting Started with Web API Testing Previous Section: Course Overview Source: "Getting Started with Web API Test Automation in Java" by Andrejs