How a developer accesses an API
This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?
The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:
Where to download the API and other tools you need.
Where to get your API key or other required app credentials.
A hello world app or some basic sample code.
During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.
Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)
Calling a REST API or other web service API
As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.
Importing a library-based API
For a library-based API, you need to import a library of code or binary functions into your development project (your application). Then you can use the functions and objects in your code. When using a JavaScript API, for example, you get the API by including a documentation
For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.
Downloading a flowerRecently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. :)
