A Tutorial on OAuth, Part 5: API Calls

If the third step, user authentication, is the most confusing, making API calls is the most tricky. Here we will look at a general overview of what making API calls is all about and then look at a basic overview of what is involved in an API call.

What is an API Call?

Let’s use an analogy to explain what an API call is. Think of how you use email. You send a message to someone and they send a response accordingly. Looking more closely at this, you are sending a message from your own username at the domain that hosts your email that is tailored to the username at the given domain you are sending it to. If the person you are sending the email to doesn’t know you, you may not get a response, or a bad one. Or, perhaps the person who got your email didn’t understand what you were saying and they respond with irrelevant information. This analogy can go a long way in explaining how OAuth and API calls work. Suffice it to say that an API call is a message sent with the intent of receiving certain information. OAuth lays out the semantics of what the messages sent and received should look like.

API calls are awesome, rather, good APIs are awesome and make web developers very happy. Every API is its own flavor, tailored to the application it is purposed for. Because of this, not every API that implements OAuth will do so in the same way. Combining this with how complex and sensitive OAuth is, this makes web developers batty and makes them want to throw things.

Now, let’s look at a more technical way of explaining what an API call is. In OAuth language, an API call is a resource request made by a consumer in order to access the protected resources of a user. Some resources are unprotected, such as Twitter’s public stream, but it still requires that the entity requesting the information be an authenticated user when making the call. The OAuth specifications define the semantics of API requests and responses.

5. Resource Request

A resource request involves sending signed parameters to a resource endpoint of a service provider. If the request is authentic, the service provider will respond according to their API specifications. There are four essential steps to making a resource request:

  1. Send Parameters
  2. Base String
  3. Signature
  4. Sending the Request

The first step gathers the parameters to send which are then used in the second step which formulates a base string that is then used in the signature. Though the HMAC-SHA1 algorithm is not the only supported method, it is the most widely used. This signature method takes two pieces of data, the base string and the consumer secret concatenated with the access token secret, and runs them through an algorithm that spits out the signature digest. The digest, or what is commonly just referred to as the signature, is then added to the send parameters and the request is sent.

Where OAuth revolutionized the process of transferring information is in ensuring the integrity and authenticity of those requests. Every request has a signature attached to it. When the service provider receives that signature it will compute the signature with the data given and then compare the signature they computed with the one that was sent in the request. If the signatures do not match it means one of three things. First, it could simply mean that the entity sending the request is authorized, but failed to compute the signature correctly. Second, it could me that in fact the entity sending the request isn’t authentic: they aren’t using the right tokens and are trying to obtain private information. Or, third, it could mean that the request sent was incomplete, similar to the use of checksums.

Each step must be executed absolutely perfect. Even if one character is misplaced the signature will be wrong and the request denied by the server. As said, making API calls is the most tricky and the technicals can be very boring and tedious. Everything has to be absolutely perfect. Hopefully, this overview of the basic technicals will help make it more clear, and even more so, hopefully, this whole tutorial can help put into perspective what a wonderful technology this is. Next time we will look at the specifics of forming resource requests.

See also: Part 1, Part 2, Part 3, and Part 4.

Categorized as Development

By Joe Purcell

Joe Purcell is a technology virtuoso, cyberspace frontiersman, and connoisseur of Linux, Mac, and Windows alike.

Leave a comment