Learn how to use APIs and do API testing

Thu Aug 25 2022

23 min read

Software development now revolves around APIs, which connect and send data to millions of daily applications. This manual will enable you to master the entire use of APIs and API testing. We will also thoroughly understand ideas like API testing, REST, CRUD, and APIs in this manual.

Complete Guide to APIs

You can also consult a Complete Guide to APIs and Cheat Sheets with all the information you require to grasp APIs fully. You can use it as a learning tool or as a reference that you can use whenever you need to remember a specific detail regarding API.

The guide includes everything from simple explanations of all concepts to the most common HTTP status codes and a list of popular APIs you can use to improve your applications.

Paw – Web API Client

We'll learn how to use Paw in this manual. It is a fully functional HTTP client that enables testing and API documentation. It is one of the most advanced API testing tools available for macOS.

However, they also have a completely free web version, which I will show you how to use. The web version, most importantly, is available for all operating systems.

RapidAPI LEARN

Furthermore, you will learn everything there is to know about APIs through RapidAPI Learn. They provide interactive lessons to learn about different APIs. You can learn by testing the data. You can observe how API requests are created and how the data is returned.

What is an API?

Let's start from the beginning. What is an API? Application Programming Interface, or API, enables the communication between two applications. You use an API every time you use a mobile app, such as Facebook, to send instant messages or check the weather.

What precisely is an API, then? An app connects to the internet and transmits data back to the server when you use it. Your phone or computer will receive the data after the server retrieves it, processes it, and then sends it back. The application then obtains that information and displays it in whatever readable format you like.

Assume you're creating a trading platform. You'll need to support features such as currency exchange, market rate fluctuations, authentication, payment processing, and much more.

But developing and maintaining such features is challenging. You can leverage API integrations to connect your software to various programs to fix these problems. Let's take another example to illustrate this better.

Real-world Example

Imagine you're sitting at a table in your favorite restaurant. What are plenty of choices to order? The kitchen is the part of the system that will prepare your order. What is missing is the critical link to communicate your order to the kitchen and deliver your food back to your table.

And that's where the waiter or the API comes. The waiter is the messenger or API that takes your request or order and tells the kitchen (the system) what to do. Then the waiter delivers the response back to you. In this case, it is the food. This is an example that everyone uses when explaining APIs.

In this manual, we'll test the APIs and do our best to understand their construction. What HTTP codes do they return in response to specific HTTP verbs or actions? What kind of data are they sending and receiving? This manual will go into great detail about everything. Let's discuss a little about security before we actually check that out.

Security

Every web application you use is accessed via a device. It might be a desktop computer or a phone. Let's imagine you are navigating to a specific application using your phone. The server is never given complete access to the data on your phone.

Likewise, the server is never fully exposed to your phone. Instead, only the information that is required is shared with each other in small data packets. Like ordering takeout, you inform the restaurant of what you would like to eat, they let you know what they will need in return, and finally, you receive your meal.

It goes without saying that everything is much more secure now that it is much more standardised. Recently, APIs have become even more secure. The majority of APIs adhere to standards, typically HTTP and REST standards, that are developer friendly, easily accessible, and widely understood.

RESTful APIs are APIs that adhere to the REST principles. Web applications employ the REST (Representational State Transfer) standard to make communication between them more accessible. The primary aspect of the REST architecture is the separation of the client and server; this allows for independent client and server implementations without knowledge.

This means that changes to the server-side code can be made without affecting the client's functionality, and changes to the client-side code have no impact on the server's functionality.

Systems that adhere to the REST principles are stateless because they use a REST API, which enables many clients or computers to access the same REST endpoints, execute the same operations, and receive the same results.

In other words, neither the server nor the client knows each other's current states. Clients send requests to retrieve or change resources in the REST architecture, and servers respond to those requests with responses that all have a similar structure.

Endpoint Anatomy

An Endpoint, or the URL we are requesting, is required for an API call. For instance, whenever you browse a particular URL, you just send a GET request to obtain that specific website. The endpoint in this instance is https://rapidapi.com/learn.

Method Anatomy

Your API request must also include a method that indicates the type of request we are making. Let's assume we're making a POST request, which means we want to send some data using the POST HTTP method.

Headers Anatomy

An API request also includes Headers, which provide additional information about the client or the server, in this case, body information.

Body Anatomy

The Body section contains the data sent to the server; for instance, assume we want to create a new user called John Doe.

This was the anatomy of an API request.

Now we'll look at the various methods available to us, POST being one of them. Let's look at the standard methods for making requests and sending responses.

Understanding the CRUD

To discuss this, we must first understand CRUD. CRUD is an acronym that stands for Create, Read, Update, and Delete. In a REST environment, CRUD is frequently associated with the HTTP methods POST, GET, PUT, and DELETE.

We can see that POST is for creating, GET is for reading, PUT is for updating, and DELETE is for deleting.

REST APIs require a client to send a request to the server to retrieve or modify data. In general, an HTTP request consists of:

  • An HTTP verb that defines what kind of operation we are performing.
  • A Header, which allows the client to pass along information about the request
  • A Path to the resource
  • An Optional message body containing the data.

We use four basic HTTP verbs in requests to interact with resources in a REST system.

HTTP Verbs

The first is a GET request. GET allows us to retrieve a single resource by ID or a collection of resources. POST enables us to create a new resource. PUT allows us to make changes to a specific resource. On the other hand, DELETE enable us to delete a particular resource.

These were only the four main HTTP verbs. There are also a few less-known verbs. If you'd like to get a full list of all HTTP actions, download the complete API Guide to understand that.

HTTP Codes

You will receive an HTTP status code when you make an HTTP request. One of the most common status codes is 200, which indicates that everything went smoothly.

Code 404 indicates that the requested resource (request) could not be found. There are numerous other HTTP status codes, which are divided into five major categories.

Everything that begins with the number 1, as in 1xx, indicates that the request was received and that further action is required. That is an informational response. The request was successfully received if it begins with 2 or is in the 2xx range. Redirections are on 3xx, client-side errors are on 4xx, and server-side problems are on 5xx.

This was just a categorisation, but if you want to see some more widely used HTTP status codes, they're also included in the complete API Guide to understand.

API Testing

I'd like to use API Testing as a real-world example to demonstrate everything we've learned so far. As I've already said, APIs are now the center of attention for software development. The good news is that testing them can significantly boost productivity and enable you to deliver software more quickly than ever. API testing will allow us to examine every component of existing APIs thoroughly.

Though API testing has many different aspects, it typically entails sending requests to a single resource or several API Endpoints and evaluating the response for performance security, functional correctness, or even a status check. Let's take a look at it in action.

We'll be using Paw for API testing. You can send any type of HTTP request with this free API testing tool. You can use it to group requests for particular projects and generate environment variables.

Paw will determine the most effective method to show anything you send or receive. It supports PDFs, pictures, and online pages and fully highlights the syntax of the majority of programming languages. Paw is aware of your mistakes and warns you. When something appears wrong, it causes you to avoid frequent blunders, such as sending a body in a GET request.

We'll review every feature Paw provides on two openly accessible APIs in this manual. Let's get going right now.

Step 1

You can visit the Paw website to start testing your APIs. Go ahead and click the "plus (+)" symbol to create a new project to get started. In the project name, you can write JSON Placeholder.

The project was created in a matter of seconds, and we can now begin creating requests immediately.

Step 2

So the API that will be tested is the JSON Placeholder API, which is a free fake API for testing and prototyping.

To learn more about this API, visit the JSON Placeholder API documentation page. You will see it's well-documented, and we can get a single resource or post sample data. e can also get all of the resources by making a get request to a specific endpoint.

Step 3

But now, let's put that to the test. To test this API, I will copy the URL https://jsonplaceholder.typicode.com/posts. Following that, we will return to our JSON Placeholder project on the paw app. Let's see how it works in practice.

We'll delete the demo request and start a New Group of requests. Additionally, we can make a new request inside of this group. Let's call it Retrieve all posts and just paste the URL there. We can copy that and paste it into the description.

Step 4

This is the most basic request we'll make. We don't need to pass any headers, query parameters, body, or auth values. We simply need to press the send button. We'll get our 200 in less than a second. Do you remember what the number 200 means? It means that everything is fine.

We can also look up the details of the request we made. We can see both the request and response headers, responses in simple text, JSON Tree, etc. But it is the Response JSON Text that we are most interested in learning more about. This is the actual information returned by the API.

This is an array of different objects, as you can see. You can also collapse or uncollapse it in the Paw app to see all the data in a nice readable format. As you can see, the API returned an array of a hundred different posts. Each post has a userId, a id for the post, a title, and a body. So you have just learned how to test one specific endpoint.

This appears to be extremely simple right now because it has already been documented. However, to create your API, you must thoroughly test everything.But now, let's move on to our second request, which is to create a post.

Step 5

Go back to the JSON Placeholder API documentation page. From the Creating a resource option, scroll down and copy the same URL, https://jsonplaceholder.typicode.com/posts. We'll return to our API Testing and create one more request after copying this URL.

We can enter our URL here and send a POST request this time. We can type Create a post in the name field, copy it, and put it in the description field.

Step 6

The BODY of the post itself must now also be passed along with the POST request. We can send it as a TEXT, JSON, JSON TREE, and so on. JSON TREE supports passing values as Key and Value pairs. As a result, each post must have a title. Assuming this is my first post, we can write Lorem ipsum...., which is supposed to be a long paragraph in the body.

We also need to pass a user ID, which in this case should be 1. Finally, now that we have this, we can press the send button again. We received a 201, which means that we successfully created new data.

As you can see, the only thing added to the JSON that will be returned is the ID. Our real post won't be added to the list of all posts because this API is only being used for testing reasons.

Step 7

We can check that by making a new request to Retrieve all the posts. Let's try sending it again.

We can scroll to the bottom and see that the last post has a user id of 10, and it's going to be an id of 100, but that doesn't mean we didn't create the post successfully, but what if we overlooked some of the important properties?

Assume we forgot to pass the user ID. Let me delete it and then send it.

As you can see, it was created again, but the author is missing this time. Depending on what you want to do with your application, this could be a bug in your system.

In my opinion, an error would be thrown here because every post must have an author. With that said, what if we removed the body and the title entirely?

Let's try again.

We only received the ID, which shouldn’t happen because we did not send any Body. The post should not exist, so this demonstrates the power of API testing. You could prevent all the unnecessary potential bugs that will cause your application.

Consider receiving all posts with different bodies, authors, and titles and only a few of these details. This will almost certainly result in an error in your application. To avoid this, return to the JSON Placeholder API documentation page and scroll down. This time, let's put it into action by updating a resource.

Step 8

We can copy the URL https://jsonplaceholder.typicode.com/posts/1 and return it to Paw, and create a New request. This time, however, it will be a PUT request rather than a GET or POST request. It indicates that we want to modify a particular resource. We can simply write Update a post inside the description.

Finally, we may go to the body and pass some plain JSON this time:

json
{
"id": 1,
"title": "This is a new title.",
"body": "This is a new post body.",
"userId": 1
}

Let's send it.

As you can see, we received the status code 200, indicating that the article was successfully updated. JSON Tree, plain JSON, and HEADERS were all sent.

Step 9

Deleting a Resource will be the final request we will implement. We simply need to send a delete request to a single resource.

So I'm returning to Paw and creating a new request right here. Let’s paste the URL and change the HTTP method to DELETE. We will also change the name and the description as well. Just write "Delete a post" in the description to do this.

Let's send the request right away.

We received a 200 status code, and no data was returned; a 200 status code indicates that our item has been deleted.

Just now, we tested a CRUD API. This is a test API; the mock responses and queries represent actual responses and requests. The resources in the database would be changed and updated if you were to perform this to your own API.

URL structure

I'd like to discuss the URL structure, which is https://jsoanplaceholder.typicode.com/posts/1. We always have the https at the beginning. Then we have a specific domain in mind where we want to go. But the last part, posts/1, is the most important. What exactly does that mean? And how should you structure your API endpoints?

I want to draw your attention to a few critical points regarding REST APIs. A resource is any data present in your database or interacting with on a server. I'll now offer you a better illustration.

A resource could be a collection or a singleton. For instance, customers is a singleton resource, while customer is a collection resource. We may identify customers collection resources using the URI /customers. The URI /customers/{customerId} can be used to identify a single "customer" resource.

This is an essential thing that I want to emphasize. You always want to name your resources plural, i.e., customers. Then you can say /customers/{customerId} to get the data about a specific customer.

Singleton and Collection Resources

If you pay attention, you might notice that this is already happening. You can see posts followed by the same situation, either plural or post. Then we'd like to get a single post. Simply do for /post if you want to get all the posts. This is the first and most crucial step.

Collection and Sub-collection Resources

A sub-collection of resources is the second crucial concept. That is, each customer can have multiple accounts. So, how do we get to that? You want to structure it as follows: /customers/customerId/accounts.

You must repeat the process if you want to access a specific account ID, /customers/customerId/accounts/accountId will be displayed. Let's look at some more best practices now.

Use nouns to represent resources

Use nouns to indicate resources; I believe this is a logical choice. There will always be posts from consumers and account users. Because nouns have attributes that verbs do not, a RESTful URI should point to a resource that is a thing (noun) rather than an action.

Consistency is key

Use consistent resource name conventions and URI formatting to reduce ambiguity while increasing readability and maintainability. To achieve consistency, use the following design advice:

  • Use forward slash (/) to indicate hierarchical relationships
  • Do not use trailing forward slash (/) in URIs
  • Use hyphens (-) to improve the readability of URIs
  • Do not use underscores ( _ )
  • Use lowercase letters in URIs

Do not use file extensions

File extensions are unsightly and provide no benefit. Removing them also reduces the length of URIs. There's no reason to keep them.

Never use CRUD function names in URIs

URIs should not be used to represent a CRUD function. URIs should only be used to identify resources and not perform any actions on them uniquely. This is extremely significant.

As I mentioned earlier, if you're just getting started with API creation, it might make sense to simply call an API endpoint, such as create-managed-devices or creating-managed-device or /get-all-managed-devices, but that doesn't make much sense.

Simply follow the structure and use plural names, as previously stated. And then, the HTTP verb will say the rest. Of course, if you make a 'GET' request to /managed-devices, it will serve the purpose of retrieving old devices.

However, if you make a POST request to managed-devices, it will create a new device. It's important to understand that you can have multiples of the same endpoint, but the action will be completely different if the HTTP verb is different.

Use query component to filter URI collection

The final item on our list is simply using query components or parameters. If you want to pass additional information through the URL, use a question mark, key, and value pairs.

For example, region=USA. If you want to have multiple key-value pairs, again, start with the question, do the first key end value (region=USA), then simply put the and (&) sign in between this and the other key end value pair (brand=XYZ). It will look like this (region=USA&brand=XYZ). This data will get delivered to the server or the front end. However, you're passing the request.

We've just covered some of the most important best practices you can use with APIs. Again, more of this will be in the document.

RapidAPI Hub

Let's go to a RapidAPI Hub. It offers hundreds of thousands of APIs that you can build your applications with APIs like the recipe, Google play store, even trip purpose prediction.

Let's use the COVID 19 data. That will provide us with a large amount of data to test on.

We can proceed to the pricing section, where we can see that it is completely free for up to 50,000 requests per month. Simply click the subscribe button.

Let's try out a few different Endpoints. Let's use Totals and getLatestTotals for now. In this case, we can begin by copying the URL. That's available on the right side, so we can copy the URL. We can do that in simple steps:

Step 1

We can open Paw and create a new project. Let us refer to it as COVID 19 Data.

Step 2

Then we'll enter our New Request. Enter the API call or an API Endpoint, and the request will be a GET. We can copy and paste the name and description. We can return to this description and copy it.

Step 3

The last thing we need to do is provide the headers. We haven't done that yet, but we need to because this API isn't publicly available. To be able to use it, you must first create an account and sign up on RapidAPI Hub. So, in this case, go ahead and copy the RapidAPI key and host from the COVID 19 data API.

We'll go under environments and manage production in Paw. We can enter our RapidAPI Host and key values here.

Step 4

We can now close this and proceed to add those Headers first. We must include our RapidAPI Host.

So let's put it here under Header's name and value just right. Go to the environment variable by clicking. Simply click that and select X-RapidAPI-Host. Now we can repeat the process for the RapidAPI key based on the Headers name, the environment variable, and the RapidAPI key.

With this, I believe we should be able to submit a test request. Simply click send, and we'll get 200 Ok.

Step 5

Let us try a few more different requests. We can, for example, use the COVID 19 data API to navigate to Country. Let's try getLatestCountryDataByCode first.

In this case, we'll simply copy the URL and use it to create a new request in Paw. We will paste it in the GET method and describe it by saying Get the most up-to-date data for a specific country, which we will paste under the name and description.

Let's see what information we need to send. The country code is a Required Parameter that we must pass. Let's just copy it and pass it through request BODYin this case.

We can either send it as JSON or use this JSON TREE to simply provide a Key and Value pair. The Key will be code, and the Value will be it, which is Italy.

Let's not forget to pass the Headers so we can copy them from our previous response, which is RapidAPI Host. The other will be RapidAPI Key, and our values are already in environment variables.

Let us now see if we can get the cases for Italy. As you can see, we received a 400 Bad Request in this case. The question here is, what is the mistake? Why did this not work? And the reason why it didn't work is that there is a significant difference between a Post request and a Get request. We're currently working with a Get request; by definition, you can't send any Body data through a Get request.

You can only make that request via a PUT. Therefore, let's pass this through the Query rather than the body, which is impossible to do. These are the get request's query parameters. You can apply what we've learned thus far.

In this instance, you can include a question mark before giving a key and value pair. Paw will take care of that, so we can just say "code" and then the command. You should be able to see that it adds programs directly here down below. You may notice that we will receive 200 OK if we submit this request. And we received the confirmed, recovered, critical, and other case information for Italy.

Conclusion

Just so we can more precisely explain the distinction between the request body and request query, I'm delighted this small error happened. That concludes this lesson. Now that you've read this guide, I hope you understand REST, CRUD, HTTP, and APIs better. You should also know how to test any APIs you develop or use thoroughly.