RESTful APIs - Part 1

Before we can discuss REST we need to make sure we are on the same page on what an API is.

API is an abbreviation for application programming interface. Basically everything we do when we write an application is using an API. Whenever you use a built-in JavaScript function or even wrapping a block in curved brackets { ... } you are using JavaScript's API and when your JavaScript is running it runs in a JavaScript engine (V8, Spidermonkey, etc) which was written against a different API, normally C/C++, and then that runs using the API the OS makes available.

I like to think of an API as a layer that gives us the ability to do something. So if you are developing an application that uses the location service in the browser you have to use the API for the location service. If you want to communicate with any of Google's services you do that through an API. Need access to the data in a database? There is an API for that. APIs are everywhere and everything to a developer.

If you want to go more in depth into APIs checkout the Wikipedia article on it.

The API Everyone Hates

A problem API's is that most API's in the world are undocumented. Whenever you write a function you are creating an API. It doesn't matter if you tell anyone about the function the fact is if you create it there is an API and if you don't document it there is one more API you will have to deal with later and without documenting it you will have to spend time trying to figure out what you were thinking.

What about that third-party API you are suppose to use for your product to send insurance data but they forgot to create documentation? Well you have send it something and see what happens. Generally speaking if you can't get documentation for a third-party API your best bet is to walk away.


You may have heard developers talk about how amazing REST is. Part of that is the documentation issue mentioned in the previous section. REST provides a lot of standards on how data is communicated and how to use the built in functionality of HTTP. This means that documentation can be much smaller and easier to read and understand.

For example, I have done some work with an EDI(Electronic Data Interchange) API. It was a horrible experience but it has been several years so I can talk about it without shuddering. To give you an idea of what EDI documentation looks like I did a search for "edi documentation" and found one for the GSA Vendor Support Center. Here is the sample EDI document This is 42 pages of text and tables only to tell you how the data should be formatted and nothing about how to communicate the data and no examples. Another point to consider is that this is for a single document. It isn't how to do all the communication with GSA, it is how to send a purchase order. In other words it is a single end point and it is only the request. It says nothing about how to tell if the request was accepted or rejected.

For a single REST example take a look at Twitter's update status API end point(Linked April 2016 so it could have changed if you are reading back through my posts). Here the parameters are covered in about a page. There is also some discussion on geo-tagging, information on the URL to use, rate limiting, an example request, and an example response.

Admittedly updating your status on Twitter takes less data then sending a purchase order but the fact that the documentation can be so succinct makes it so that helpful documentation is more likely to exist and so that while creating the documentation additional helpful information can be provided.

Next time

This post covers some of the background reasons for having REST but next time I will cover how REST works and point you to some tools to get you started in making a RESTful end point.

comments powered by Disqus