Thoughts on API Best Practices API Management and Infrastructure Blog

Consider an API to unlock ‘dead data’

Book digitizing made the news last week, as Google announced a deal to digitize up to a million books from Italian libraries. Despite some author and publisher resistance, similar efforts are proceeding in Europe, including Norway’s Bookshelf project and Europeana.

What is the motivation for digitizing vast libraries of books?

Yngve Slettholm of Kopinor summarizes it well, “The vast majority of books are out of print and can be considered commercially dead.” “This creates an extra source of revenue for older books.”

What does this have to do with APIs?

How much ‘commercially dead’ data, content, or services is your company sitting on? Are you fully monetizing your assets? If you gave yet-known 3^rd parties access to data or content locked in your company, what new business opportunities and revenue streams would be created?

That’s what an open API does. It unlocks data and content, giving it the potential to be consumed in new, innovative ways, and monetized. Via an API you can get the broadest possible distribution for the lowest cost.

One example of this is BestBuy’s Remix program; BestBuy opened the Remix API and now BestBuy can be accessed via mobile apps and in new ways and places where its customers are. Another example is Sears which has opened it's vast product catalog, and TransUnion, which made its core credit report and credit monitoring services available to 3^rd party financial companies.

It is not always clear who will use the capabilities you expose or how. But one thing is for certain, if they are not accessible, they will not be used.

The book digitization efforts also hold some lessons for how to manage such a program, which I’ll cover in my next post.

SXSW discussion on API trends and adoption

Ross Turk shot a great video panel at SXSW on trends in developer and API adoption.

Sam Ramji and Greg Brail from Sonoa, Laura Merling from Alacatel-Lucent, and Martin Tanlow from 3scale talk about what they're seeing in world of APIs, from the latest mobile and social apps to Alcatel-Lucent's Open API strategy for developers building on service provider networks.

Cloud computing is a double play

Joe Weinman recently wrote that any business-focused CIO must first ask:  Why do cloud from a business perspective?

Joe makes the great point that technology will only be important if the business value is clear and compelling. CIO's have a small number of projects that they can really focus on in any given year, and major initiatives must have a compelling rationale or won't get supported by senior leadership. 

What could be more compelling to senior leadership than finding new revenue streams?

While senior IT leaders may still be concerned about being viewed as a cost center, and look to the advantages of cloud computing to reduce IT cost, savvy IT execs will find a way to help create new revenue streams for their company.  A great way to do that is to create new business channels by opening APIs.

So why not get a double play?

You can do both… have a  more business-relevant discussion with senior leadership about how to spur new revenue growth, as well as start to utilize cloud computing.  Sonoa’s API management solution is helping companies like TransUnion Interactive , SilverPop, and MySpace create new revenue streams by opening their APIs, and Sonoa is available both on premise as well as a ‘cloud service’.

Design your API for adoption with ‘true REST’

"The only reason you'd have only a SOAP API is because you 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!