During the development process, you may come across some ”technical jargon” or terms that go over your head. If you’re ever in a meeting where the developers sound like they are speaking a different language, it is perfectly fine to ask for an explanation in layman’s terms. While the terminology and processes might be unfamiliar, the concepts aren’t as complicated as they may first appear. The term “API” is a great example and it’s a topic that may come up multiple times throughout the development process. So what is an API and what is the purpose of an API?
What is an API?
API stands for Application Programming Interface. The purpose of an API is to facilitate communication between software. They provide a format for applications and devices to talk to one another and exchange data in response to commands.
This Request/Response pair is a fundamental component in an API. It involves a sender/receiver relationship. Much like a website server responds to user interaction, an API is what web and mobile applications use to interact through code. In essence, a call to an API is akin to “clicking a button” on a website, as you have a connection between two platforms.
User Interface (UI) vs Programming Interface (API)
If the user interface (UI) is considered the “front end” of a system — what the user sees and interacts with — then the Application Programming Interface (API) can be considered the “back end” of the system. It largely conceals the complexity of the commands and data requests behind the scenes.
So, how does an API work?
API Commands and How They Work
When an application wants to talk to another application, it makes a “call” to the other application’s API. This call usually occurs over the internet, using HTTP (Hypertext Transfer Protocol).
To make this request, you need a few pieces of information. Some fundamental pieces include the endpoint (which is just the website URL to which you’re sending the request), any necessary authentication data, the message header and the “verb” (or request method). Some requests will also include a message body.
| TECH FACT: Have you ever wondered about the purpose of information that comes after the .com portion of a website URL? It’s the endpoint and optional parameters for a request. Endpoints act as subdirectories, indicating different pages on a website. Optional parameters are tagged with a question mark and give additional information as the request is made (such as an API version). |
There are multiple HTTP request methods (verbs), such as GET, POST, and DELETE.
- The GET command is used to request, retrieve or read data.
- POST is used to send or write data.
- DELETE is used to remove data.
Once an API receives a request, it can return data in different formats, such as JSON or XML. Depending on how you access the API, you may observe a string of code that’s returned on the back end. The results can also be viewed on the front end after the data is translated and displayed by the web browser or application that you are using.
The Authentication Function of an API
APIs are not always publicly available or accessible. Some APIs require access tokens to authenticate a request. Other APIs may not be accessible if they are located on a local server and network that is not connected to the internet. APIs might also be hidden behind a firewall that blocks traffic and prevents unauthorized access.
In addition to being hosted on local networks and on-prem servers, APIs can be hosted in the cloud. As long as the applications have a way of communicating with one other (i.e. over the internet), they can initiate API requests and transfer data.
Example of APIs in Action
Now that we know more about how APIs work, let’s revisit our earlier website example. Imagine you are shopping online and find a product that you like. You want to know if it is in stock at a store near you, so you type your zip code into the box and hit enter. The website then returns the store locations and number of products available. Simple enough, right? But let’s apply the process of an API request to understand what happens behind the scenes.
As a user, by hitting enter, you submitted a request using the web browser. In turn, the web browser sends a GET request to the application’s API, asking it to pull inventory and store location data. The API pulls the data from the respective servers and it then sends back a formatted response. When the web browser receives the response, its job is to translate the response into a visual representation that can be viewed in the browser by the user. In this case, the end user is you, as the online shopper.
Another real-world example of where you might encounter an API involves a web-based platform that integrates with and pulls data from various platforms and SaaS accounts. For instance, you might use an online marketing platform to manage e-newsletters and newsletter subscribers (among other things). You may need to authorize the use of an API and corresponding authentication token so the marketing platform can communicate with your Google Analytics account in order to render insights and analytics for your on-site e-newsletter subscriptions.
So how are APIs relevant to a software development project?
The Importance of APIs in the Software Development Process
APIs are employed extensively during the software development process. Three examples include displaying data, supporting functionality and integrating with existing resources.
If you’re developing a web app, you may be interested in displaying information that currently exists in a company database. For instance, as part of your enterprise software project, you might like to display employee profile information when your users log in.
It would be costly and inefficient to develop a secondary database with duplicate copies of the employee information. Instead, you can make a call to an API to retrieve the data from an existing employee database through an HR portal.
APIs allow you to make calls to existing applications and retrieve data that is needed for a software project. That data can then be displayed in the mobile app, web app or custom software platform.
API Integrations for Existing Internal and External Applications
During the discovery phase of the software development process, the software development team should ask you what existing systems and applications you would like to integrate into your new software.
Start off by evaluating your existing company resources and compare these resources with the functional requirements of your new project. Once you have defined the necessary integration requirements, your development team will likely utilize APIs to perform the actual integration.
Updating APIs
When developers make changes to an application, such as adding another screen to a web portal, they will build an extension for the current API. Whenever you add functionality to the software, it may require the creation of additional code to call the correct API at the appropriate time.
Common API Issues and Errors
During development and in the course of using a software program, it is not uncommon to experience an API error. However, when an API “fails,” it is not always due to the API itself.
Developers will tell you that API error messages are not always helpful. Since APIs serve as the middleman between end users and servers, anything that goes wrong along the communication chain may reveal itself as an API error.
Due to this data path, you don’t always know where the error came from. For instance, it could be due to a bad request or a problem with the application that sent the request. The issue may also arise from the application the API is attempting to retrieve data from. Alternatively, the developers who built the API could have been the ones to define the error messages. These factors often lead to error messages that are not indicative of the actual problem.
But while some error messages may leave developers scratching their heads while troubleshooting, here are a few common issues that may occur:
- Authentication errors – A user’s authentication may have timed out, the request may have included a bad authentication token or perhaps no authentication token was given at all. To fix this issue, the developer would just need to verify and validate the authentication process.
- Searching for something that doesn’t exist – Whether there is a typo in the request or the resource doesn’t actually exist, a bad request will not return the correct data. Verifying that the correct information is included in the request will help to solve this issue.
- File Issues – Occasionally, a request may return a corrupted JSON file or the wrong endpoint may be set entirely. This could crash the application or cause the API to return an invalid data set. Data validation and checking endpoints are two ways to combat these problems.
- HTTP errors – These would include network or internet connectivity related errors. The API may be left waiting for a response and could time out. Checking your internet connection and re-initiating the request is an easy way to correct this issue.
Depending on the issue, the developers may set error messages to display for the end user. Most API issues will involve a code review and verifying that the code includes the correct request, the correct API and the correct resource endpoints.
The Purpose of an API Revisited
To summarize, APIs are integration tools that handle requests and provide a way for applications to communicate and exchange data. They provide access to data from third parties, enable a variety of functionalities, and can serve as a security measure through the use of authorization tokens. They help both users and programs to navigate a website or application. In short, APIs are a key to success in the application world.
Whether you are interested in developing a mobile app, custom web app, or piece of custom software, the team at 7T is ready to help. Our team can develop an intuitive user interface and backend system for your team, but we also provide services related to cloud integrations and data governance. To discuss your development project, connect with our team today.
