How to Quickly Learn APIs

A few weeks ago, I asked if there was a topic that followers on Twitter would like to see covered on the blog.

I create a Poll with the following ideas:

• Coding for newbies
• How I got into technology
• Developer Tips
• How to Quickly learn APIs

There were over 600 votes and “How to quickly learn APIs” received the most votes coming in at 34.5%.

In this post I share:

• processes that I run through to get my head around a new API
• tips for testing  new APIs
• common code you’ll find most APIs need you to write

Authentication and Authorisation

After you’ve identified the API you need to work with, one of the first things to figure out is if you need to use authentication.  Common authentication and authorisation approaches include:

• API Keys
• Basic Authentication (username and password)
• OAuth

Each have their own pros and cons, but this is one of the first things I look at. API Keys are often generated from your selected API admin screen and random collection of characters. This method and Basic Authentication are usually the quickest to implement.

What format is data returned by the API?

Spend a few minutes to identify which format data is returned by your selected API.  Most modern REST APIs use JSON. Older APIs may use XML. Take a note of the format as it will affect the way or tools you use to process data.

Which Endpoints do you need?

Interacting with an API involves using one or many endpoints.  The best place to start is the developer documentation or API reference guide. For example, here we can see the Twitter API Developer documentation:

I’d quickly skim the area I was interested in (performing a User Lookup), then I’d check out the dedicated link for the endpoint I was interested in users/lookup:

After selecting this, I’m taken to the nuts and bolts of this endpoint:

I can see from this screen I need to create a GET request, there are constraints around the data I can fetch and the endpoint URL https://api.twitter.com/1.1/users/lookup.json .

What values or data structures does each endpoint return?

Now that you know the endpoint(s) you need, it’s helpful to know the items or structures you can find in each response. Sometimes you’ll find that the information you need to get isn’t fully returned in one API call, this means you’ll need to one ore more subsequent calls to get at the data you need.

Paging and Sorting

Does the API your consuming support paging and sorting? If so, you often need to handle this when coding your integration.

A common pattern in most modern APIs is the use of “count” and “next_token” and “prev_token” parameters.  These are used to tell the remote API how many records to fetch with each call and let you browse through pages of API results.

Testing the API

By this point you’ve figured out the authentication method you need to use, are aware of the data you’ll be working with and have identified the endpoint and data structures each endpoint returns.  It’s a good point to make a connection to the endpoint and see if you can create a request and fetch data.

You can start coding, but my preference is to use a tool such as Postman.  This let’s you quickly create a request, setup authentication, add parameters and send it to the API.

With Postman, you simply paste in the API endpoint, key in the parameters, and click Send. After you’ve verified that data is getting returned you can start to think about writing code.

Creating boilerplate code to interact with the API

Now that you can make an end to end test with the API, it’s a good idea to write code and standardise each of the steps. I find creating private methods for each of the following steps to be helpful:

• Authentication
• Generating Access Tokens
• Paging
• Each discrete API Endpoint (e.g. CallGetUsers)

I find it useful to encapsulate these multiple API calls into a collection discrete private method in C#.  I’ll then create one public method for my code to call. This normally gets added into a service / manager type class.

For example, here you can see a Service class I have created to consumer Twitter API:

UserService userService = new UserService(oAuthInfo);

UserModel userModel = userService.GetUser("jamie_maguire1");

List<string> users = new List<string>();

users.Add("jamie_maguire1");

UsersModel usersResults = userService.GetUsers(users);

Under the hood,the method GetUsers handles authentication, calling the get users endpoint, parsing the JSON response and outputs a Domain Model containing user details for the client code to use.

Final Tests

After testing code, it’s useful to carry out performance testing and gauge how many calls per second/minute your API can make. Most APIs available on the web will have rate limiting assigned to each endpoint.

This means that you can only make a given number of requests within a certain period. This ensures the uptime of each endpoint and prevents bad actors from consuming too much of the server resources.

During the early phase of you API integration you most likely don’t need to worry about this but as you start to use it regularly you will need to extend your integration to handle this.  A common approach I use is to:

• Log the start time of the API request in a variable
• Log the number of requests my service class makes
• Log the end time of each API requests

I then use a combination of all three to ensure that each service class adhere to the number of requests I make doesn’t violate the APIs terms of service.

I dump this information into a logging database table that I can easily report on periodically. It’s a pattern I’ve used for Instagram and Twitter API integrations that has worked well.

Summary

In this blog post I’ve shared the steps I go through when I need to quickly learn a new API.

Are there any tools and steps that you go through?

Drop a note below!