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 <script> element in your HTML page. The <script> element loads the library supplied by the API. In this case, the download of the API happens every time the browser loads the HTML page. This type of API is sometimes referred to as “client side”, because it runs in the browser on the user’s computer. To see an example, take a look at the documentation for the Google Maps JavaScript API, which describes the <script> element needed to load the API library.

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 flower

Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree.🙂

How a developer accesses an API

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 2 January 2016, in Android API, APIs, technical writing and tagged , , , . Bookmark the permalink. 1 Comment.

  1. This is very helpful. For a particular product’s REST API, I might add that the user might have to download and install something and configure the settings for accessing the REST API. For example, on my machine right now, I have my company’s product REST API set up to use localhost, but the REST API could be accessed via another machine if I had set it up that way. Flickr, Google, etc. have publicly available URLs on the web, so of course no downloading and configuration is necessary.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: