How an API works

A quick look at what an API is and does

I often see questions on the Web about how to do things with an API (Application Programming Interface). Often the questions suggest that the person asking the question doesn't really know what an API is or how one can be used. In this article, we'll take a brief look at what an API is and how it works.

MODX logo

A Typical Question

A user, for example, might ask, "how can I use JavaScript with an API to manage my contacts?" This question can't be answered without a lot more information about where the contacts are, what the server expects, and what client is being used to access the data. There is no single JavaScript API, and an API may, or may not, use JavaScript.

What's an API?

API (Application Program Interface) is just a general term that usually refers to communicating with a remote System. Let's use the example suggested in the question above. There’s a remote server that contains information about your contacts. (The contacts could be stored on a local server, but in that case, you usually wouldn't need an API to manage them.)

To manage a contact’s information, you need to send a message to the remote service (referred to as the API Server). To update a contact's information, for example, the message would contain the new information (data), like the contact’s new email address, and the "action" you want it to take, which in this case is "update my contact." The action could also be something else: "create a new contact," "delete a contact," "send me a list of all my contacts," "send me a list of contacts in a particular state," or whatever the remote service is capable of.

The information in the message may all be packed into the URL (this is called using the get method), or it may be hidden from view (this is called using the post method). Some services require one or the other, some allow both, and some require get for some requests and post for others.

When the remote server gets the message, it tries to do what you want and returns either some information (if you asked for any), or at least a success/failure indication. If the message sent to the remote server is not in the right format, is missing required information, or if something else went wrong, the server will return an error message.

The remote service should have the documentation for its API up on the Web somewhere. If it’s MailChimp, for example, Googling MailChimp API documentation would find it. The documentation will tell you how to communicate with the remote service.

The point of an API is that you don’t care how the remote service handles the requests as long as they’re acted on correctly — and the remote service doesn’t care what method you use to send the messages to them as long as the messages are formatted correctly.

For an API that uses Get requests (the info is in the URL), you could send your message with a regular HTML web form, an Ajax call in JavaScript, a cURL call in PHP, or even by just typing everything in the URL in your browser’s address bar.

If you type in this address to the GitHub API, for example, you’ll be asking for a list of other URLs you can use to get information from GitHub.

If you try some of the URLs listed there, you may get a message telling you that you forgot to include credentials in your message:

{"message": "Requires authentication"}

or they may work (the emojis one works).

If you have been playing with the GitHub API, you may see a message like this:

    "message": "Not Found",
    "documentation_url": ""

That message could mean one of two things. It may mean that you've entered an invalid request to the API. It could also mean, however, that you've exceeded GitHub's API rate limit. There is a limit to how many anonymous requests you can make to the API. You can get around this if you have a GitHub account (it's free) by getting an access token for your account and sending it, and your GitHub username, along with the request. In that case, there is still a limit but it is quite generous (5000/hour).

Typing all API requests into the browser’s address bar is ridiculous, so you’d much rather use some program (referred to as the API client) to do it for you. The API client acts as a go-between between you and the API server. The API client lets you select the action, input any necessary information, and tell it to send the message to the remote service (often, with a “Submit” button of some kind). The client also handles the returned message from the API server. It alerts you to any errors, confirms successes, and may display any information you have asked for.

Some Finer Points

Many APIs have an API client you can download. Others have libraries you can download that contain building blocks you can use to create your own API client. Some (like GitHub) have both. Notice that GitHub has libraries for a variety of computer languages.

If you are creating the API client yourself, however, you need to know a little more about the process. Google the name of the API and documentation (for example, GitHub API documentation). The API documentation should tell you the URL(s) to use to make various kinds of actions (technically called endpoints), whether the endpoint expects a get or post request, what variables can be used to control the action, and the format of the response.

In almost all cases, the response will be in JSON (JavaScript Object Notation) format. For example, this request to the GitHub API shows my GitHub repositories. If you paste that URL into your browser's address bar, you'll see a list of all my repositories in JSON format. GitHub is kind enough to format the result for you, so it's fairly readable (other APIs are not always so courteous). Think of the colon (:) as an equals sign, the curly braces as surrounding a particular section of information, and the commas as delimiters separating each single piece of data.

If you want to use PHP to make the request, you'd use either cURL or fopen(), set the required options and call either curl_exec() or fopen(). If you're using PHP, you'd typically convert the response to a PHP array using PHP's json_decode() function.

If, instead, you want to make the request in JavaScript, you'd set the options and the URL in an Ajax call. You can do this in plain JavaScript, but JQuery can make programming Ajax request much more convenient, especially if you want to support older browsers.

Building a working API client is beyond the scope of this article, but API documentation usually has plenty of specific examples showing how to do it.

Coming Up

In the next article, we'll look at how to tell if you can do a fast-forward merge in Git without actually merging.

Looking for high-quality, MODX-friendly hosting? As of May 2016, Bob's Guides is hosted at A2 hosting. (More information in the box below.)

Comments (0)

Please login to comment.