Understanding Web APIs

Web Application Programming Interfaces (APIs) are incredibly important in modern software development where applications need to be able to communicate with many other systems and sources of data. However, providing and using APIs adds a great deal of complexity to software development which makes things difficult for first-time learners.

In this article we’ll examine the concept and typical usage of an API as well as the details of the requests and responses that power modern web development. This will set us up well for a second article on debugging issues in API development.

This article is written without a specific programming language or server technology in mind (e.g. ASP .NET Core or Spring Boot) and should be helpful to anyone familiar with the basics of software development.

If you’re looking to get into software development, I’d recommend you check out Tech Elevator’s 14-week program as this article is written as a supplement/troubleshooting guide to accompany that material.

What are Web APIs?

Web APIs allow code to either work with other people’s code (if you are consuming an API someone else built) or allow other people to call your own code (if you provide an API).

Think of an application like a drive-through restaurant. The restaurant has walls that hide the details of the kitchen and how the food is prepared, but customers can drive up and look at the menu to see what food is offered by the restaurant. They then make a request to the restaurant through a specific point of communication (the microphone on the menu or the drive-through window) and the restaurant will either fulfill that request or provide some other type of response.

This is what our code is like. We may have many classes and methods in our application, but we only want people outside of our organization to be able to call specific curated methods on our code. These methods that are available for others to interact with are our API.

A web API specifically means that other systems can communicate over computer networks or the internet to talk to our specific application and get a response to our inquiry. These messages are called web requests which we will explore shortly.

In web communications, we refer to the system making the call as the client and the system receiving a call and generating a response as the server. As a result, web communications follow a client/server communication model where the client makes requests and the server generates responses. This is sometimes referred to as a request/response communication model.

What are Web Requests?

Web Requests are specific messages that flow from one application to another over a network or the internet. Every time you open your web browser and navigate to a web page it actually makes a web request out to a specific server. The server will then generate a response that gets returned to the application making the call (in this case, your browser). This response typically includes some data that the application can use to accomplish its goals.

In the specific case of web browsers, they will make a special type of request called a GET request to a specific web address. This request gets routed to the server hosting the website you’re trying to load and that server knows how to handle that request by returning an HTML file along with a 200 OK status code indicating that the request succeeded. Your browser will then interpret the HTML into a web page that the user can view and interact with (the details of this are beyond the scope of this article but are addressed in Tech Elevator’s curriculum).

But not everything that makes a web request is a browser. Many times applications will need information from things outside of their own organization. For example, a travel application might need to know what the weather forecast is in a specific area or the current gas prices in a city. These pieces of information might be available elsewhere on the internet from other organizations which already have an API available for them.

In this case, your application could make a web request to fetch that data from another system. Instead of getting back a web page, the other API might return raw data in JSON or XML format that your application could then work with.

Parts of Requests and Responses

Whenever I interview someone for an API-related position, I like to ask them to describe the parts of a request and a response. This helps illustrate the candidate’s understanding of web communication which tells me a bit more about their ability to debug issues with web services.

Each web request features the following parts:

• A verb (also called a method) indicating whether you are trying to GET, POST, PUT, or DELETE some piece of information (among other options).
• The specific web address that you are looking for. For example, https://www.techelevator.com/columbus identifies a specific campus within Tech Elevator’s site
• Headers are included in every message and identify information about the calling application. Headers can also be used for authentication and security purposes.
• Some requests will have a body. The body is the contents of the request you are making. POST and PUT requests commonly have bodies while GET and DELETE requests should not have bodies.

When the server returns a response, it will consist of the following parts:

• A status code indicating what happened with the request (more on this later)
• A response body typically containing the information requested or an error message.
• Headers from the server, which may include new pieces of information.

It is important to keep these components in mind as many issues with API communication can stem from things like forgetting authentication tokens or a message body or can be resolved by paying attention to the response from the server.

Closing

As you can see, APIs are critical to software development. In fact, roughly a quarter of Tech Elevator’s 14-week program is centered around APIs since APIs really are that important to software development.

Because APIs are complex and have a huge learning curve, debugging them is a difficult, yet important acquired skill. In the next article, we’ll discuss the incredibly important (and difficult) topic of how to debug web API problems.

The post Understanding Web APIs appeared first on Kill All Defects.