What is an API and How Does it Work?
Once upon a time, around 1999, Pat decided he really wanted to make a fansite for the TV show Two Guys, a Girl & a Pizza Place. So, Pat went to work building out the website: downloading pictures of the cast and researching their bios, getting episode descriptions, finding links to press clippings and downloading promotional images.
It was a lot of work, but he managed to keep it going for about a year. Eventually, Pat got lazy and tired and the site went into disrepair. Then, sadly, in 2001 the show was canceled.
Prior to the show’s untimely death, Pat wished for a way to get the newest information on his site without him having to manually add it. Unfortunately for Pat, just about the time he gave up on his fansite, the world was introduced to its first application programming interface or API.
What is an API?
At a basic level, an API is a way of getting information from another source to use in your website. There are two basic actions involved in using an API: a request and a response. In a practical sense, an API is a website, so the actions are the same as you’d expect when you go to a website. You enter a URL like sitecrafting.com and hit enter, that’s the request. Then the browser displays the SiteCrafting website, that’s the response. APIs are the same, except they’re not as pretty.
When you visit the URL https://api.tvmaze.com/shows/1506, for example, the response is from an API dedicated to information on TV shows, in this case, the listing for Two Guys and a Girl.
As you can see, it’s not pretty, but it does provide you with all sorts of information including the status of the show, when it started, and a description of the show. Typically you don’t see an API, it is used behind the scenes to get information that fills out data for your website. Then within the bowels of your website that information is cleaned up and presented in a more attractive form.
APIs are available for all sorts of things, from the mundane like dad jokes and TV show information to useful things like the weather, mapping data, payment gateways and job searches. In fact, you’ve probably interacted with at least a dozen APIs just to get to this blog post.
How to Use an API
There are a few basics to the usage of APIs. First, you need to find out how to gain access to the service. Typically that means learning if there are authentication requirements for the API. Most APIs today use what is known as OAuth2 for authentication and authorization. Using Oauth2 you will usually have a Key and an API or Client Secret. Both of these values are used to authenticate who you are and what you’re allowed to do with the API. Not all APIs will have these two values, some only have an API Key and others, like the one above, don’t have any authentication system and are free to use by the public.
Secondly, once you’ve got access to the API then you need to learn the endpoints needed to do the tasks you’re hoping to accomplish with the API. Endpoints are basically just URLs that ask for information or tell the API to do something. If the API is well designed the endpoints will be pretty descriptive of what they do. For example, with the API we used before ‘/show/’ tells the API that we’re looking for information about a show and the ‘1506’ is the ID of the show we’re looking for information about.
Example: The endpoint: http://api.tvmaze.com/people/49061 tells us that we’re looking for a person with the ID of 49061 – in this case Traylor Howard, best known for her work on Monk and also Two Guys and a Girl.
Lastly, you should know the usage limits of the API. Each service has its own set of rules in this regard and they are based upon server and/or bandwidth constraints. The TV Maze API we’ve been using limits users to 20 calls every 10 seconds. Other APIs will have several levels of limits for calls per minute, hour, and day. The point here is that you should know the rules of the API you’re planning to use, so that you don’t accidentally cross the line and get put in API jail. Additionally, you should know going in if the way you plan on using the service is a good fit with the service you want to use.
Once you have those basics in place all that’s left is to actually use the API and for that you’ll use some combination of services your website has available to pull down responses from the API and process that data in usable ways. I can’t tell you how to do that in your situation, but if you need some help give us a call.
Building an API
Before starting to build an API you need to ask yourself if there is value in building one. A lot of work goes into creating a solid and user-friendly API. If the market for your API is large enough then you should definitely build it out, but if the benefit to your users is minimal it’s probably worth holding off. Alternatively, several companies are what I like to call API first companies, meaning that they built their API first then created all their other apps — web, mobile, desktop — using that API.
If you’re looking at building multiple apps, building an API could be a useful way of creating consistency between your apps. Nonetheless, before going forward with building an API you need to decide if it’ll be worth the cost in time and effort.
Once you’ve decided to build an API, you then need to go about the process of creating answers for users asking the questions listed out above. Constructing an API is not difficult, but doing it right requires a lot of preparation. If you do your prep work and use a good framework, making an API could be a very good thing for your business.
Whether you’re trying to bring about interest in a mediocre television show from the 90s or you’re trying to provide your users with data curated from other sources, APIs are a valuable tool for your website. Learning how to properly deploy them in your web application — to either consume data or provide access to it — will make your site better and your clients more likely to use it.
