What is an API and How is it Essential to Building Great Software?

Small stormtrooper screwing in lightbulb, photo from Unsplash: 2james-pond-185593

What is an API?


API(noun): An application programming interface. In layman’s terms, a way for computers to talk to one another in a predefined format.

APIs define a clear way for computers to communicate with one another. Think of an API as a way to query information. In simplistic terms, if I say: “What color is the sky?” an API should respond with “Blue.” But APIs can do a lot more than that, and can respond with a variety of information. APIs have some standard formats for response. The most commonly used data format is known as JSON (Javascript Object Notation), a lightweight and easily readable format. We’re big fans of Star Wars here, and conveniently there’s an API for that. If I send a message to the Star Wars API for Characters I’ll get this response for Luke Skywalker:

GET (Request to get data)

API Response:


As you can see, the API will send back some of the basic information about Luke Skywalker, indicating that his hair color is “blond,” he is “male,” is a height of “172,” and so on. With this kind of information you can imagine how we could build a simple app that tells you all of the various elements about each of the Star Wars characters.

Not only can APIs be used to serve data, but they can also be used to create or update. There were new characters surfaced the the newest film The Force Awakens, we could allow our users to create or update certain data on our API. We can do this by sending data to the API, in a format that looks almost identical to the data we retrieved above.

POST (Request we send to create data on the API)
Data we send to the API:


Now when we request a list of all characters, the Rey will be returned in that list.

Why Do I Need One?

Imagine you didn’t use an API for your Star Wars app and then Star Wars Episode VIII hits theaters. Guess what? You’ve got to update your app/website with all of the new characters! If you had used an API, simply updating the database of characters once would mean that your app would have worked perfectly to include all the information, even after the new movie without having to deploy changes to your application or website.

By avoiding hardcoding certain pieces of information, we can also reduce the amount of content necessary to store on our application. Instead of storing high resolution images in our application for all characters, you can leverage an API and your app will only download the images of characters that the user loads. Even if the data is relatively small, the more places you store data, the more likely it is that your data will be out of date.

This kind of architecture allows for flexibility when data changes, saving you from pushing updates to your website, iOS, or Android applications. Change it in one place and all of your applications will have the latest information. No waiting for your application to go through a multi-day review process with Apple or Google Play.

Star Wars API iOS screen

An API would deliver relevant and updated information to any app, as seen in the above example (note: the above is a designed mock-up).

How can we make sure we’re doing all we can to be a good partner?

So now you get what an API is, but how we can make sure you’re building a great API? The examples above are a bit simplistic so it is important to know that building a great API requires a lot of care and thought. But there are many things that you can do both before a project kicks-off and during its development that can make things easier for your partners.

1. Come up with a clear contract before the project starts

Before teams begin to work it is important to set expectations from the get-go. From past engagements we’ve found that defining the roles and responsibilities of what the API will and won’t do before the project starts is a great first step. There are certainly times when you want to build an overly prescriptive API, but through hundreds of projects we’ve found that when it comes to anything data related, the API should always be responsible. Apps and websites should refrain from hard coding anything that could conceivably change.

Once your API is live, documentation is key. Developers, whether within your organization or public, need to know how information can be retrieved, created, or updated. Good documentation allows developers using your API to have a clear understanding of how to use it and what information to expect. This allows for a much faster development cycle.

2. Make your API fast and responsive

Because your end-user will never experience your API directly, a major benefit it can provide is speed. If your API is slow, your users will notice. When an app or website checks in with your API, you want a fast response. There are many ways this can be solved. Caching is a beneficial technique which allows you to store the response of requests that are infrequently changed. For instance, if Luke Skywalker is often requested and his information rarely changed, we can save his data in memory (faster) instead of querying the database (slower) every time a user makes a requests for him. This is not the only way to implement caching, but a simplified example.

3. Deploy Automated Testing

By building an API you’re creating a contract with the applications and websites that consume it. If your API goes down, it also takes down all the applications that are using it. This is where automated testing can be extremely valuable. We use a tool called Runscope to periodically check in with our APIs which allows us to proactively solve issues. If a developer makes a change to the API and we have well written tests in place, we’ll know if that change might break functionality before that change goes live. Proper testing can save you from experiencing critical production issues, and also help developers save hours of time debugging.

4. Use RESTful principles

If you aren’t familiar with the term REST (short for representational state transfer), your development team will be. This methodology or way of thinking helps ensure that APIs are designed in a way that other development teams can interact with your API  by following RESTful principles.  As a developer, knowing that an API is following RESTful standards, it allows them to make certain assumptions while interacting with your API and speed-up the development process.

In this world of increasing connectivity, APIs are the information highways that provide data and direction to billions of applications and websites we use every day. If you’re concerned with bringing more customers to your doorstep, then building a solid API should be top of mind.

Today, most businesses sell and provide a variety of physical goods, digital products, services, and experiences. As connectivity and computing increases across the world and devices like Google Home, Amazon Alexa, and Artificial Intelligence Chatbots increase a company’s market share. Having a fast and easy to use API will allow you to open your doors to business on new platforms. If you build your API correctly, it will quickly start working for you.

Here at Raizlabs we have experience building incredibly effective and fast APIs. If your team is interested in learning more and the possibility of collaborating, get in touch.