RESTful APIs are becoming a standard for gluing apps in a Web oriented environment. Twitter, Google and a host of other Web properties have thrived by developing their own REST APIs. The use is so widespread that there are some developers who maintain that the API should be developed before anything else.

Still, a steep learning curve exists in building APIs. There is a surprising lack of resources or standards to go by. This is especially true when integrating security through OAuth, the now most common security protocol for APIs on the Web. There is little that tells you how to build an API the right way with security in mind.

At DjangoCon in Portland yesterday, Tareque Hossain presented a discussion titled: RESTful APIs: Promises & Lies. Hossain is a senior technologist with the PBS Education Technology Team. He shared his team’s experience in building an API and the lessons the group learned along the way.

I caught up with Hossain at DjangoCon and did an interview with him. But let’s first look at the approach Hossain and his group took as it is an interesting story about how the group approached its API development and in the process enhanced an open-source technology for the Django community.

Here’s the slide deck Hosssain showed at Djangocon.  His lesson can be summed up as follows:

• Your API is only as good as the resources it delivers. That means defining resources accordingly.
• Resources are not the only thing your API delivers. API responses should be uniform and wrapped in envelopes with associated metadata such as HTTP status code, error messaging and pagination data.
• Automate your methods for offering formats.
• Version control is critical.
• Use OAuth
• To effectively use OAuth, work with an API framework. Django is Hossain’s focus so that means choosing django-piston, tastypie, django-rest-framework or dj-webmachine.
• Hossain used django-piston for PBS Learning Media, which has built in Oauth support with a varirty of pluggable items such as pluggable resource handlers, pluggable emitters, and pluggable authentication.
• Hossain and his group enhanced django-piston for the open-source community. They added pluggable envelopes, form error feedback and anonymous tokens.

Here’s my interview with Hossein after the talk in which he sums up his experiences in building APIs.

Services Angle

A new generation of apps is needed for the emerging modern infrastructure. A critical aspect of that is the API. Services organizations need to hire more developers to build apps. But just as important are the processes for building APIs. The trick is in finding the right way to do it.