Checklist for building an API

The API Strategy & Practice Conference in Amsterdam was a very interesting look into the world of API’s. I was mostly interested in what building an API involves, and I’d like to share what I’ve learned in this regard. Building an API should consist of the following steps: Design > Mock > Test > Build > Publish > Operate > Engage. Let’s take a look at each of them:

Design

The first thing to do is something which is often ignored: you really need to design your API before you start building it. You’ll need to think about what functions you need, what the parameters are going to be and what the responses will be. This information should be described in a structured way and you’ll need to share this information with your API consumers so you can receive feedback before you actually start developing.

Of course you can create a word document to specify your API, but there are better ways to do so. The most well known ways are Swagger, API blueprint and RAML. I have chosen RAML because of its excellent tools support, most notably, the very nice API designer.

Image

The advantage of specifying your API in a structured way becomes evident very early: after specifying your API, you can see a nice list of your calls, and you can even launch a mock server with 1 click off a button where you can call your own defined calls and get a (mock) response back.

After you’ve completed your design, you should send this documentation to your API consumers to get early feedback and change your specification accordingly.

While designing your API, you should consider the following:

Your API should be platform agnostic

A good API can be powered by any technology. So don’t use SQL queries as GET parameters if your backend is powered by SQL and don’t return package names if your backend is powered by Java.

Security

You need to think about security up front. Using OAuth 2.0 is a good choice (see here for a nice, simple explanation), but you can also pick SAML for example.

Versioning

You need to think about versioning upfront in order to prevent issues in the future. You really don’t to have calls named EXTCallName, EXTCallNameV2, EXTCallNameV3 (I’ve seen it happen).

Mock

When you have specified your API you should be able to generate a mock server in a matter of minutes. In case of RAML, you’d do this by using the online tool. You can also use SoapUI where you can create a pretty advanced mocking service with support for multiple responses per call. Another way is to create a project in Mule Studio with APIkit installed and generate your flows with your .raml file. The advantage here is that you can gradually change each call to be an actually working call in stead of giving a mock response.

You should use this mockup for testing (see next step). You can also use this mock to allow your API consumers to already start using your API before development on it has even started.

Image
An overview of the calls, with the “Try it” functionality to get a mock response.

Test

This mock server should also be tested. You can use SoapUI to do so. You can do this to be sure you get the correct responses. The best thing about it, is that you can use the same test later to test whether your actual backend still confirms to the same specs.

Build

How to build your API depends entirely on the platform that you choose. For me, 2 things have worked out really well in the past: Grails and Mule Studio.

Grails

Grails makes it really, really easy to make a simple CRUD backend. The main advantage is that a lot of features you need for creating a backend are created for you. For persistence: if you define a domain class, you’ll get free save, get, find and delete methods. Likewise: adding a maintenance screen for your domain is 1 line of code. Generating/parsing XML or JSON is 1 line of code as well. I’d recommend using Groovy/Grails Tools Suite to start developing.

Mule

Mule on the other hand is designed for making integration work easy. For example: you can make an HTTP backend which queries your database, whose result then transformed to JSON, an order is entered in SalesForce and your sales employee gets an SMS message. Hell, it even makes sense to plug in the grails backend you just made if you want to integrate it with other systems or want to add things like OAuth support to it. You can start developing for Mule with Mule studio.

Code generation

You can use the specification for your API which you create in step 1 to get you started while developing. You can use this in Mule studio to generate a project for you, but also code generation (for example for JAX-RS) exists.

Test

After you’ve completed one of your calls, you should use the same tests you created earlier for you mock backend and try it on your new API and see if they still validate. You might also want to test things like the performance of your code.

Operate

When your API is live, you’ll need API management for the following:

  • Contract enforcement (some clients should be able to do more than others)
  • Managing security and managing security policies
  • Usage monitoring (how often is your API used? Which are the most used calls? Who is using my API?)
  • Monitoring of quality (what is the average response time for my API? Which calls are the slowest? / Do I get any crashes?)

Engage

Creating an API portal

You’ll want to engage with other developers if you want your API to actually be used. The most important thing (after having a good API) is to have a developer portal with good documentation (you should be able to generate all the technical specification from the design you made in step 1).

You’ll also need a way for to test your API. Please do your best to restrict potential users as little as possible. For example: if your API isn’t free, make sure your users can still try your API without paying. Also, make sure users won’t experience rate limitations while testing your API.

Another way to make testing your API as easy as possible: make sure your API can be tested in your API portal, so your users won’t need an IDE to get a good feel for your API. In the screen you’ll create, you might want to consider not just showing the raw data returned from your backend, but also showing this data in a visual way. For example: when you return a geolocation with data, you could present this data on a map.

CitySDK preview
CitySDK is a good example of how you can allow potential developers to get a good feel for the SDK in an accessable way.

You don’t need to create your API portal yourself: there are several services on the internet who help you with just that.

Marketing

Even if you have a fantastic API with a great developer portal, this doesn’t mean that developers are actually going to use your API: you’ll need to market it. In case your API is an internal API, a simple e-mail will probably do, but in other cases, you really need to think about how you are going to reach developers for your API. You might want to start with a small amount (e.g. three), before you open up your API to the world.

You’ll also need to think about who your target audience is. According to a research by developereconomics.com, only 50% of API users are using the API in order to earn money. Therefore, you might want to market this non-professional audience as well.

Interact with your developers

Think of how you are going to interact with your developers. You can let them provide feedback, rate and discuss calls add a general place for discussions, etc.

Advertisements

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 )

Google photo

You are commenting using your Google 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 )

Connecting to %s