Flavio Ishii

Guidelines for Designing an API

In my quest for knowledge on how to design an API, I found some very useful resources and tools. There is much to discuss and read on this topic, and on this post I recommend a few starting points. I’ve worked with (consumed) quite a few API services. Some are a pleasure to work with, but others are not. One particular API I worked with broke all the rules mentioned in the Joshua’s video below. It’s actually quite funny, now, but it was a pain to figure it out and communicate with them. So, if you are thinking about creating an API service, especially an open API service, please, please follow the design considerations from the resources mentioned below or other similar experienced parties.

What is an API?
In plain terms it is a library of code accessible from different components of a software system or from third party applications. Used by developers in order to integrate with existing systems and encourage code re-use. Served and consumed by Web applications, mobile applications, cloud servers, private servers…

Why would I build an API?
Perhaps you want to organize your code into an API and sell it as services to third party developers. My own reason is for supporting various client platforms from one core code base.

How do I design an API?
The truth is, all developers are API developers by nature, but most of us just need more discipline. Software Engineering principles are applied when designing an API, as demonstrated below by Chief Java Architect at Google and author of Effective Java, Joshua Bloch.

Joshua went into a lot of issues for designing API’s but there is a lot more to it than that. For instance how do you protect your API? How should you analyze its usage? You can find more details on these issues in a paper produced by Sonoa Systems.

Are there tools for API’s?
Cloud providers may have their own built in security mechanisms and analytic tools, but they may not be suited to your needs or you may not even have access to them.

There is a cloud-based solution that provides protection and analytics called Apigee (app-e-gee) from Sonoa Systems. A New York Times article on the former Microsoft Open-source Chief, now part of the Sonoa team, gives a little background and introduction of the company. Apigee is hosted in EC2 so if your API is hosted in EC2 as well you’ll get some communication performance advantage. The video below gives you a quick glimpse of Apigee in action.

I’ve signed up for a free Apigee account and I’m excited to use it, once my API is finished.

Update: Please check out Guillaume’s comment below, there’s a similar tool by 3scale. Something interesting that you can do with their solution, but not limited to, is use a plugin for Google App Engine!

Where should I host my API?
There are really only two choices here: in the cloud or in a private network. It depends on your needs. My preference is in the cloud because I don’t have the resources or the desire to administer an IT infrastructure.

Other resources:
This Little Manual of API Design
Media API: Security Best Practices
If you have any resources please share them below. I’m still learning as well