Written by Danielle Emma Vass. This post first appeared on her personal blog.
I have spent the past couple of weeks teaching students to understand API’s at codebar (an amazing organisation everyone should check out and support). This blog post series is an attempt for me to clarify in my head what things mean, and potentially used by other newcomers to API’s. So any feedback, particularly from people who have never used an API before to improve these articles will be *massively* appreciated.
Before starting it would be beneficial to have some basic knowledge web development using HTML and JavaScript.
What *is* an API
In the old days, websites were just static containers of information. You might have a webpage for a village which contained information about who lived in which house. Whenever any changes needed to be made, someone would have to change the HTML and re-publish the website.
This obviously isn’t ideal when information changes so fast!
Websites will now keep their information stored someplace else (usually a server). The page can then ask for the information it wants to display e.g. all the new village updates. This mechanism of asking for and getting information back is called consuming an API.
Examples
What does an API look like?
There are two parts to using an API; the request, and the response data we get back.
Request
A request is always a URL (what we type into the address bar in a browser), below is an example request to get funny cat gifs from the Giphy API.
api.giphy.com/v1/gifs/search?q=cat+funny&api_key=dc6zaTOxFJmzC&rating=pgThe first half of the URL (everything before the question mark) is the endpoint we’re connecting to, which happens to be the Giphy search endpoint.
We can then specify some query parameters after. API’s have various different parameters that are either required or optional and should be documented. For our example the parameters mean:
- q = is the query string, which for us is cat and funny, remember you can’t use special characters like a space in a url
- api_key = a key to prove who is accessing what. If we were to make a private app using the giphy API we’d have to apply for our own key, so they can see how many requests we’re making, and maybe charge us if we start using a lot
- rating = we don’t want any accidentally rude gifs to come back so we’ve set it to be PG (from the movie rating system in the USA)
Note: Sometimes API’s will have these parameters as a JSON data object instead. We’ll go through what JSON is in a minute…
Response
As the request URL is also a URL we can paste it into a new tab and look at what data is returned. To most people (including me) this will look like a garbled mass of letters, which looks impossible to understand. Most good browsers will allow you to install a JSON formatter to make it easier to read:
JSON
Pronounced Jason, JSON is a relatively new way of expressing information. In the past we used XML, which looks similar to how HTML is written, to express information. You have a tag, and the content in the middle. So, I could write a person object like so in XML:
XML was really difficult for JavaScript to turn into useful information it cared about, so JSON was invented - which stands for JavaScript Object Notation.
Inside you could have :
- key value pairs, e.g. “name” : “Danielle Emma Vass”
- lists, or arrays e.g. “programming_languages” : [ “Android”, “iOS”, “JavaScript”]
- Objects e.g. “Address”: {“city” : “London”, “country” : “United Kingdom”}
- Combinations of the above — check out http://www.json.org/ for more in depth examples
Why?
1 Data is separated from the view
An important programming principle is to split the data away from the interface you will be using it in. This allows you to write cleaner code which will make it *much* easier later if you want to make any changes to either the data, or the view at different times. You can search for the Model View Controller pattern for more information on this.
2 Using the data anywhere
Having a mechanism to ask for data can be beneficial if you want to use that data in multiple places such as a website, Android app, iPhone app etc. If you update that data, it’s *much* faster for everyone else to also get that updated information too!
3 Security
Many API’s are locked down and you have to ask for permission to use them, Giphy are super nice to provide an open key. Typically most API’s will ask you to write an application for access. This means they can validate whether you should be getting back the information, and ensure you don’t get any information you’re not supposed to. For example, if you were to use the Twitter API, you’d have to use your key so you could see your tweets. If any of the people you follow have private tweets (not open to the public) these would get returned. But, others using the API would not be able to see those tweets (unless they also followed/are followed by the private tweeter).
Conclusion
Hopefully that gives you some idea of what an API is and how to use one! If anything didn’t make sense please reach out either by commenting or any of the channels linked below - chances are if you didn’t understand it, neither did someone else less likely to tell me! So please help!
Next in part 2, we’re going to look at using the Giphy API to make a really simple site that allows visitors to find some gifs that match their search query.
Written by Danielle Emma Vass — www.de-velopment.com
Twitter — @de_velopment
GitHub — @daniellevass
