Thoughts on API Best Practices API Management and Infrastructure Blog

Design your API for adoption with ‘true REST’

"if you only offer a SOAP API you are saying that you effectively hate 80% of your addressable market." - @sramji

There's usually little argument that a REST API is easier to use than a SOAP API.

But how important is it to be 'truly' or 'strictly' RESTful? That is, adhering to standard HTTP operations or 'verbs' - GET, PUT, DELETE, POST - on well defined resources, as opposed to the common practice of embedding 'verbs' or operations as methods in a GET URL.

Typically, security is cited as the big advantage of 'true REST' (with some good discussions here and here).

However, a truly RESTful API may help you boost developer adoption. For example, imagine a 'shopping cart' API:

While the above API isn't 'truly RESTful', it's not that hard to use.  But you do have to learn the individual operations and this can get cumbersome if there are a lot of them or as the API evolves.

Instead, this 'true REST API' may be easier to learn and predict as you use more features.

What if we want to list all the shopping carts in the system at any one time? We would add that via an HTTP GET to:

http://api.shopping.com/carts.xml

Query parameters can still serve a purpose - making it possible to specify additional options. For instance, imagine a very large shopping cart, and you want to "paginate" the results. To look at items 20-29, you might use a URL like:

http://api.shopping.com/carts/X.xml?start=20&;count=10

Bonus: True REST makes analytics easier

It's a lot easier to build reports that segregate and analyze traffic by URL than to build logic that tries to do this by methods or combination of methods. Good API analytics helps you optimize features, debug problems, and weed out traffic that can slow down your service.

What if your 'non-strict' REST API is already out there?

It might not be that big a deal if your API is very simple or 'read-only' API with information that isn't too sensitive (such as a free search API). Or you can map a non-RESTful API into a 'truly RESTful" API with custom code or API management tools thatperform API transformations.

* A note on POST VS. PUT

* One way to insert an item in the shopping cart is to use POST to update the shopping cart by sending it a new item. In this case, we are using POST to send the server an instruction that essentially tells it to insert some new content to the existing resource. This is why we use POST -- it is like an "update" in a database.

Alternately, we could add the item by using PUT to a new URL, such as:

PUT http://api.shopping.com/carts/X/items/Y.xml

But if we do this, then we need to somehow give our item some sort of unique URL by picking a value for "Y". This is kind of a strange thing to do, so it may be more natural to use POST and have the response include the URL for the new item, so that we may retrieve it later using GET or delete it using DELETE. Still, sometimes using PUT like this makes sense.

This all comes down to the difference between PUT and POST in the HTTP spec. POST modifies something that already exists, and how that thing is modified is up to the server. PUT replaces the entire contents of the URL with new data. Plus, like GET, HEAD, and DELETE, PUT is idempotent, which means that if you call it more than once, it has the same result every time, whereas POST may keep doing what you ask it to do over and over again

Yes, REST security does exist

A recent article "Why REST Security Doesn't Exist." postulates, "REST does not have predefined security methods, so developers define their own."

Some good points in here (such as 'don't roll your own')  but I might not completely agree with the premise.

One of the fundamental principles of REST is that it builds on the HTTP protocol -- and the HTTP protocol very much does have "predefined security methods."
 
The basic HTTP protocol supports a way to plug in different security schemes. It also supports OAuth, two-way SSL, and many other mechanisms. Not only does HTTP allow for many security schemes, many of which like HTTP basic are defined by IETF standards, but it also supports a mechanism that allows a server to identify when a request was rejected, if the request was rejected because the security credentials were invalid or because an authorization check failed, and whether the rejection was permanent or temporary. HTTP also includes a mechanism that allows the server to issue a "challenge" that asks the client to re-send a request with a particular type of credentials if it has them. This all adds up to a security method that has proven quite robust over the years and has been extended with new methods such as OAuth when new problems arise.
 
Also, don't forget that different APIs demand different security requirements. An API that offers product catalog information, for instance, with no way to update the information, does not require strong authentication if the owner of the data intends that data to be public anyway. A simple "developer key" that uniquely identifies the sender of the request -- yes, a username "without a password" -- is just fine for that type of API because it is used to identify the user for various tracking purposes, and is not designed to prevent unauthorized users from gaining access to the data.

Cool article and great to see some discussion on this!

Mobile Location-Based Services - don’t forget the Telcos

TechCrunch recently posted on a Juniper report on “Mobile Location Based Services"  This report taps on the potential for this new wave of powerful apps – like letting your phone geotag the video you just took and posting it to Facebook with a Google Maps link;  one-button dial to a nearby restaurant discovered through your social network; or dynamically billing for high-value media content via the operator.  

Companies like Google, Foursquare, and Nokia are mentioned as on the forefront of many of these services.

But don't forget the Telcos - they have rich location based services with network data and a huge customer base.  Exposing APIs and working with third party content and service providers is critical for telcos and network operators. 

But Telco APIs can be complex.  Our view is that the Telcos that focus on making these APIs as simple and accessible as those from consumer Web players can be winners in MLBS.  We talk about these and other issues in detail in our new Telco 2.0 Whitepaper.

Apigee vs. Sonoa ServiceNet for API management

In a few years, most of your internet traffic might come in not through your website, but instead through mobile devices, tablets and affiliate partners accessing your services through APis.  For two years, we've been helping enterprise customers accelerate their API strategy and deployments with Sonoa ServiceNet.    

Last year we released Apigee as a tool for developers building apps with APIs.   Apigee provides free, self-service website for API analytics and protection. Hundreds of developers are using Apigee to monitor APIs they are consuming (such as the Twitter, Flickr, and Facebook APIs) or APIs that they are providing.   Here are some example apps. 

How do Apigee and Sonoa ServiceNet compare?

It's much like the difference between Google Analytics and Omniture. Apigee (like G analytics) is a free, self-service API analytics and management tool that provides coarse grained analytics and basic throttling policies.  Sonoa ServiceNet is an enterprise-scale API management platform that provides a rich policy framework for customized, complex policies and enterprise-levels of scalability.  While Apigee is available as a free service,  Sonoa ServiceNet is available as both an on-demand an on-premise (both hardeware and software) offerings.  Also, Apigee is itself an app built on the Sonoa ServiceNet platform.

So if you are a developer building an app that uses APIs and want basic API analytics and rate limiting in 5 minutes - give Apigee a spin.  If you are a product or engineering executive thinking about an enterprise API strategy or roadmap, consider these potential requirements and take a look at Sonoa ServiceNet for industrial-strength enterprise API management.

But can you hold the API to the SLA?

Great article by Jonathon Feldman in Information Week recently with some steps for CIOs to take before getting into cloud computing.   One is to insist on SLAs from cloud providers, especially considering the natural tension from the provider's perspective between high-availability and low-cost operations.

Absolutely agree.  But to build on this - remember that scene from Seinfeld where Jerry is at the car rental counter -  "Anybody can *take* a reservation, the important part is to *hold* the reservation."

Often, cloud and API providers will agree to SLAs, but have limited means to enforce or verify the SLA is held. Many SLAs are just 'on paper' with minimal enforcement or monitoring.  This gets especially tricky if you need to discuss financial penalties. 

Consider how you will monitor, meter, and audit API traffic and content between you and your partners - from your side - in order to pinpoint problems, protect your organization, and especially if you need to enforce penalties based on SLA misses.