Nearly every project we work on includes an API integration. Most clients don’t know they need one when they first come to us, though. APIs are what allow apps to work with other apps and take advantage of the massive amount of data that’s already out there.

When building a new web or mobile app, it’s important to focus on building only what’s really required for the app, and then expanding on it later. Should an app build its own weather service that needs to be updated constantly so it can provide the latest information, or is it easier to request that information from an existing source? In another case, would the app benefit from building its own social network so users can post things to it, or would it be better for your users to be able to just post to Facebook or Twitter? The third-party services provide great benefits to apps, and most apps require integrations with these services to be successful in their business goals.

When communicating with a third-party service like Facebook or a server with weather information, developers use APIs, or Application Programming Interfaces. Apps send information to the API services as “requests” and receive information back as “responses.”

APIs in action

As an example, consider a simple weather mobile app. When the user opens the app on their device, it determines their location using the GPS in the device. Next, it begins the conversation with the server. The app builds a request, including the location information, in a format that the server understands. This is similar to filling out a form on a site, with fields for information the site requires to do its work. The app sends this request to the API server. The server receives the request, looks up the weather for the requested location, and sends back a response. The server’s response is formatted in a way that the app has been built to comprehend. The app interprets the response and displays the updated weather information to the user. The image below illustrates this request/response model.

If the app allowed users to submit weather updates, the process is only slightly different. The app still sends a request, but rather than getting information about the weather as a response, the API server might respond confirming the success of the submission or with an error explaining why it couldn’t handle it. The app still has to handle the response from the server. The example image has been updated below to illustrate this new conversation between the app and API server. The app has updated the server in this case, rather than our previous example where the server provided an update to the app.

In either of the above cases, it’s critical that the app format the request properly and handle the response format properly. There are various standards that can be used for submitting API information, and typically an API will require one specific format to be used. Often, this format is different from the way that the data for the app is stored, so that requires some interpretation to make things work. Building the requests and handling the responses is the real work for developers integrating with an API, and is where they’ll spend most of their time.

Assessing an API

When looking at third-party services to integrate with for an app, there are a few things to consider that will make integration easier and make developers happier while working with the API.

• Documentation

Accurate, current, and easy to understand documentation is great to see. The clearer, the better. Examples also go a long way when exploring a new API.

• Security

Good developers work hard to secure their users’ data. It’s important to see evidence that external APIs take security seriously, too. Often, there will be a key/password required make a request to a server. Other sites require more authentication to prove that the requests are legitimate. It’s a glaring issue if at least some form of security isn’t included in the API.

• Useful Errors

When something fails during a request the application makes, it’s much better to have too much information about why it failed than having a simple message of “An error occurred. Sorry! Try again later!” High quality errors help the app inform users why something went wrong, and can give developers an idea on how to fix an issue. Developers don’t want to spend time repeatedly making requests to an API to figure out why it’s failing. They want to build more features for the app and keep making it better for the users.

• Responsiveness

Whenever an app makes a request to an API server, there’s a period of time that the app (and thus, the user) has to wait for a response. The shorter this time is, the better for the users, and the happier they’ll be while using the app. Waiting too long on an API response can result in lost users as they move on to another app or site that might be faster.

• Longevity/Stability

The more critical an API is to an app, the more important it is that the API be stable and be around for the long haul. If an API request structure changes next week, that could break the app for users. Good services won’t often drastically update or remove API options without warning developers ahead of time. What happens if the API or service goes away? Is there another, possibly more stable, option that would work in its place? It’s important to consider, because the app will have a dependency on the API and could be broken if things change.

Why APIs?

Integrating with an API is a great way to make an app work better and more effectively for users without the overhead of building things from scratch. It also helps in the development process by letting the developers focus on unique ways to use the data or interact with other services, rather than having to gather that data or build those services.

All apps need data in order to run smoothly. We can help you leverage existing data streams to put the right information in your users’ hands. Ready to chat about your project? Let us know!