APIs in Apps: Getting the Basics
If you’ve ever used the internet or an app, you’ve interacted with an API.
APIs are an absolutely critical component of the web today. They are a set of routines and protocols that every digital native is aware of in theory. But the reality is, very few people truly understand how APIs work, and how they will play a part in designing and building a mobile app.
Developers who have built APIs get their value, and the software development market is certainly moving towards using APIs in more clever ways to build business. But for an aspiring app developer, or someone who hasn’t yet built or used an API thoroughly, let’s go through some of the basics of how connecting APIs in your app can help you build a great mobile application that users will love, with even less effort than you think.
What is an API?
(Note: In this piece when we say API we are referring to REST APIs)
Strategy experts Bala Iyer and Mohan Subramaniam described APIs as a technology that allows firms to interact and share information with other firms on an unprecedented scale, taking advantage of the far-reaching progress in digitization and the rising influence of software in our day-to-day lives.
In simple English, Application Programming Interfaces are sets of rules or instructions which manage or control how one application can talk to another.
“An API is a machine-to-machine interface rather than a user interface. It allows developers to access the functionality of other software modules through well-defined data structures…” — Marieke Guy, Jisc Good APIs report
How an API works
APIs make use of fixed communication protocols. These govern how computers can communicate effectively. Data for an API is usually retrieved from a server and HTTP is the common protocol used when talking to the server.
Communication in HTTP centers around a concept called the Request-Response Cycle. The client sends the server a request to do something. The server, in turn, sends the client a response saying whether or not the server could do what the client asked.
To make a valid request, the client needs to include four things:
- URL (Uniform Resource Locator)
- Method
- Headers
- Body
URLs become an easy way for the client to tell the server which thing it wants to interact with. Of course, APIs also do not call them “things”, but give them the technical name “resources.”
The request method tells the server what kind of action the client wants the server to take. In fact, the method is commonly referred to as the request “verb.”
The four methods most commonly seen in APIs are:
- GET — Asks the server to retrieve a resource
- POST — Asks the server to create a new resource
- PUT — Asks the server to replace an existing resource
- DELETE — Asks the server to delete a resource
Here’s an example to help illustrate these methods. Let’s say there is a pizza parlor with an API you can use to place orders. You place an order by making a POST request to the restaurant’s server with your order details, asking them to create your pizza. As soon as you send the request, however, you realize you picked the wrong style crust, so you make a PUT request to change it.
While waiting for your order, you make a bunch of GET requests to check the status. After an hour of waiting, you decide you’ve had enough and make a DELETE request to cancel your order
Headers
Headers provide meta-information about a request. They are a simple list of items like the time the client sent the request and the size of the request body.
URL Parameters
Simple request data is often provided to the API using the request’s URL in what are called “URL Parameters”.
URL Parameters come in two main flavors:
Path Parameters
- Values embedded directly in the URL. For example, in http://foo.com/users/2, the value 2 is a Path Parameter indicating which user to access
Query Parameters
- Simple key -> value pairs which are generally used to narrow the scope of the requested resource(s). For example, in http://foo.com/users/search?name=tom, the API would filter all users by name with the value tom.
Body
The request body contains the data the client wants to send the server. Continuing our pizza ordering example above, the body is where the order details go.
A unique trait of the body is that the client has complete control over this part of the request. Unlike the method, URL, or headers, where the HTTP protocol requires a rigid structure, the body allows the client to send anything it needs.
These four pieces — URL, method, headers, and body — make up a complete HTTP request.
HTTP Responses
After the server receives a request from the client, it attempts to fulfill the request and send the client back a response. HTTP responses have a very similar structure to requests. The main difference is that instead of a method and a URL, the response includes a status code. Beyond that, the response headers and body follow the same format as requests.
How APIs build on HTTP
By now, you can see that HTTP supports a wide range of permutations to help the client and server talk. So, how does this help us with APIs? The flexibility of HTTP means that APIs built on it can provide clients with a lot of business potential. We saw that potential in the pizza ordering example above. A simple tweak to the request method was the difference between telling the server to create a new order or cancel an existing one. It was easy to turn the desired business outcome into an instruction the server could understand. Very powerful!
This versatility in the HTTP protocol extends to other parts of a request, too. Some APIs require a particular header while others require specific information inside the request body. Being able to use APIs hinges on knowing how to make the correct HTTP request to get the result you want.
How are APIs used?
APIs give another program or application access to data, information or functionality so that it can share or use some of the “host” program’s resources easily and with minimum restrictions. This facilitates a sharing of information. This is subject to certain rules defined by the person who is doing the sharing. The whole point of an API is to define how it is used.
Here is a super simple example with tools and services we’re all familiar with:
Yelp takes advantage of Google Maps APIs as well as providing one of their own for others like Facebook to use. When you search for a restaurant on Yelp, it pulls data from its own database, as well as data from the massive stores of data available to Google and Google Maps. This means you look for the address of your local Italian spot and it shows up on a map brought to you by Google, Yelp has made a request on Google Maps’ API to get that data and make it available for you inside their app. Later, when you post your score and review that restaurant on Yelp, you may see that other users can in fact see those reviews and scores on Facebook. This is just another example of data sharing data between applications via APIs.
What are the advantages of APIs?
The advantage of APIs is that they are Future-Ready. As needs change, APIs help to support unanticipated future uses. Making data available via API can support faster and easier data migration and improved data quality review and cleanup. APIs can provide greater flexibility in delivering services; for example, using a service that accesses a backend system to power a new product.
In a recent article in ZDNet, Dion Hinchcliffe, executive vice president of strategy at Dachis Group, was quoted as saying that the benefits of opening up an API can be strategic. The Austin, Texas-based consultancy focuses on social technologies for businesses.
Hinchcliffe highlighted revenue generation and traffic growth as “very real benefits” of open APIs but noted that the most important outcomes are having direct access to innovation and company sustainability.
“APIs are a way to cost effectively scale a company’s businesses in many simultaneous new directions as well as tap the ingenuity of a large partner ecosystem, all while largely fire-walling risk” — Dion Hinchcliffe
Hinchcliffe explained that traditional business partnerships, joint ventures, and product integrations are time-consuming and expensive to create and maintain. In comparison, the open API model is “designed for nearly effortless, asymmetric scale”, where almost all the work needed by the partner is pushed to the other end of the relationship, he said.
All the API provider has to do is “create the API and support it well”, he added.
First, rather than focus on the value of the API per-se, it’s helpful to think of the value of the effect of the API. Remember it’s the organization’s core business which is valuable. An API is a channel to provide new types of access to the existing value an organization provides.
Another common misconception is that for an API to be valuable, API users must be prepared to pay for it. This is true only if the API itself is the product. In most models, this is not the case. APIs are usually driving some other metric (pizza sales, affiliate referrals, brand awareness, etc.) and the value of the API to the organization will be measured differently. Consequently, the value of the API to users is the effect of an API call, rather than the call itself.
Security
Given that an API can be subject to the common attacks occurring on the web, security is a valid consideration. However, an API is also capable of being secured in exactly the same way as normal web pages — so there are plenty of well-known security measures that can be put in place. The categories to consider are:
Secure communication. Transport Layer Security (TLS), as seen on secure “https” or “padlocked” websites, provides for encrypted communication between the consumer and provider.
Authentication. Ensuring that a consumer is who they say they are can be done in a number of ways, and an advanced and well-known method is OAuth — it is used by Twitter, for example.
Authorization. This is about determining what the authenticated consumer of your API is allowed to do. For example, it is possible to limit the number of requests a consumer can make, or provide read-only access to particular consumers.
Connecting
When two systems (websites, desktops, smartphones) link up through an API, we say they are “integrated.” In an integration, you have two sides, each with a special name. One side we have already talked about: the server. This is the side that actually provides the API. It helps to remember that the API is simply another program running on the server. It may be part of the same program that handles web traffic, or it can be a completely separate one. In either case, it is sitting, waiting for others to ask it for data.
The other side is the “client.” This is a separate program that knows what data is available through the API and can manipulate it, typically at the request of a user. A great example is a smartphone app that syncs with a website. When you push the refresh button your app, it talks to a server via an API and fetches the newest info.
The same principle applies to websites that are integrated. When one site pulls in data from the other, the site providing the data is acting as the server, and the site fetching the data is the client.
Using APIs
REST is a standard, found everywhere HTTP is used, with a clear vocabulary for actions (for most intents and purposes, composed of 4 words: GET, POST, PUT, DELETE), and a /very/flexible/instruction/construction/system/that/can/model/any/object/hierarchy/or/statement/.
BYO-Back End
As an example of APIs in action, we’ll talk about how we’ve made the most of them in our tool. Dropsource gives you the power to include any data you want in your apps, as long as it is driven by an API that meets a few basic requirements. We provide the endpoints inside the app you are building to link to your API, and you will use Swagger to document your API and upload that Swagger file to Dropsource. Although our goal is to eventually be agnostic to API design, there are a few requirements an API must meet before it can be Dropsource compatible.
To work with Dropsource apps, APIs must:
- be RESTful
- support JSON
- if using protected services, follow one of these authentication schemes:
1) Basic Auth
2) OAuth2 (password & implicit flow)
3) API Key - have logical status code responses
Dropsource API integration
Developers are able to integrate existing cloud APIs into Dropsource by using Swagger which provides superior API tools that make APIs easier for both users and machines to interpret.
Put simply, Swagger works by allowing a developer to document everything about their API in JSON or YAML (paths, parameters, authentication schemes, protocols, data model definitions, response and body definitions, and API meta information). Once all of this information is documented, Dropsource can learn about your API and make all the relevant options available on the Workbench, our visual development environment, so that you can easily connect your app’s interface to the API endpoints.
Here is a link to learn about Swagger and its awesomeness:
There are also tools out there to help convert other API formats into Swagger like Convertron, the API Transformer.
For more on Cloud APIs in Dropsource, see our full post on the topic here.
Conclusion
The Harvard Business Review summarizes the value of APIs as follows:
Today, a firm without application program interfaces (APIs) that allow software programs to interact with each other is like the internet without the World Wide Web. Just as the World Wide Web opened up the internet’s potential for use by billions, APIs — specifications or protocols for how to exchange information or request online services from an organization — are allowing companies to grow businesses at unprecedented rates by sharing services with external firms.
We agree wholeheartedly.
Quick PSA: One thing we firmly believe is that adopting and embracing a standard for API communication and documentation that makes APIs easier and more consistent to work with (AKA embracing the Open API Initiative) would make the internet a better place. This will allow for systems to communicate more fluently as well as reduce the learning curve it takes to work with each API because they will be communicated in the same format.
Rant, over.
Now, you may have ideas for or even have already started developing a stunning application which is set to please users and serve its market well. Congrats! But when you can add meaningful API links into that app, it’s like adding vibrant swaths of color to a black and white, monochromatic image. It simply changes everything.
The many amazing, and trusted services and data connections that APIs make available to your app will open up massive opportunities to delight your users and grow. When you factor in tools that take advantage of the open API system, now building an app and connecting APIs into it can be both powerful and convenient.
☞ Please tap or click “♥︎” to help to promote this piece to others.
Check out Dropsource for your next app development project. Our platform helps dev teams efficiently build & ship quality native apps by converting your team’s app designs into concise, extendable native source code.
