Editor’s note: this is a “Sponsor Post” by one of our long-term sponsors. These posts are clearly labeled as such, but we also want them to be useful and interesting to our readers. We hope you like the posts and we encourage you to support our sponsors by trying out their products.
When publishing an API, there are two preparatory steps to take before jumping into implementation. First, create metrics for determining the success of your effort. Secondly, take a good look at what you already have so that you can find out what you need to do before you publish.
Keep in mind that you do not need to push everything out the door at once. If you start small and focus on delivering a few useful core calls, you will entice early adopters. These developers will give you the kind of feedback you need so that you can rapidly refine your API. Iterating quickly and listening to users of your API will help you build a healthy user community and create evangelists.
In helping dozens of customers prepare their APIs for publishing, Mashery has observed what works, what doesn’t work, and what is on the horizon. Here are some of the lessons we have learned.
Get Your API Ready
It appears that beyond the enterprise, SOAP is being left in the dust. REST is now the dominant approach in API publishing. The advantage of REST is that it is explicitly built on top of and leverages HTTP in ways that web developers are already comfortable working with. This makes development faster and easier. JSON-RPC is exhibiting growth as developers seek to integrate natively with rich JavaScript-powered user experiences. XML-RPC appears dormant and is used less widely than SOAP and REST. The emphasis has decisively shifted in favor of making content easier to consume, and if you use an approach that allows REST or abstracts to REST, you will be making life easier for developers who want to use your API.
What does this mean if you are already internally using an API that has been built around SOAP and want to publish it? At Mashery, we use protocol transformation to allow customers to deploy a REST implementation of a SOAP-based API. There are a variety of techniques for protocol transformation, and the approach we take depends on the API and the development tools being used.
Your API may also need to be cleaned up, split from a larger API set, or both. It is not uncommon for an internal API to develop cruft over a long period of use, and sometimes calls that are fine for internal use are too sensitive for use in a public API. Larger established companies frequently have a patchwork of APIs from having acquired smaller companies over the years. In all of these cases, there are workarounds that will allow you to publish a “lite” version of your API, giving you some breathing room as you build a new and improved API. For example, method limiting or filtering can be used to strip out unwanted elements from the WSDL.
Be Careful Abstracting Network Calls
Recently there has been a big push to abstract network calls by mapping API method calls directly onto server-side object methods. This may not always be a good idea because treating server-side objects and client-side objects as equals via web services can lead to serious inefficiencies.
For example, consider exposing a data access object directly via a web service. Broad-ranging queries to that object may result in very large quantities of data being pushed back through the web service. Now imagine that web service running on a mobile application over an EDGE network. By exposing the data objects in such a way that local and remote access to the object is treated equally, the result may very well be an unusable mobile application.
Instead, invest the additional time in crafting a broader suite of web services that access data in ways that are most commonly used, so that the smallest possible payload can be returned. In fact, building an API specifically for mobile web use will help you identify potential roadblocks early. The end result will require more up-front design work on the API, but will also yield higher-performance mobile applications and blazing-fast traditional web apps.
As with any optimization approach, moderation is best. You also do not want to wind up with an over-abundance of small calls when a handful of medium-sized payload calls will do the trick. You may want to consider support for batch-style operations in your API, so that a series of calls can be sent in one request, and the result of those calls chained together can be returned as the batch call payload.
Make It Cacheable
If you can cut down the number of round trips between client and server, you can increase the overall performance of your API. The more data you can cache, the easier it will be to cut down on those round trips. So, look for places in your API where uncached data is being used and, where possible, make that data cacheable.
The payload of an API call sometimes has a lot of uncached data; for example, a key value that is passed back each time the call is used. Sometimes extra payload data is inserted for debugging purposes, particularly with JSON-RPC, but it is easy to forget to remove the extra data from the payload later. Elements and attributes that are uncached can seriously reduce the overall performance of an API, while also increasing server resource use. Strip out the uncached elements and attributes and you will likely see a noticeable performance improvement.
Mashery has implemented caching for customers who need faster response times. The results are impressive: they usually see performance improvements of 50% or better for cache-related calls. If it is cacheable, you should cache it.
Remember, a New Approach Is Always Just Around the Corner
Earlier we mentioned that REST is the most popular approach for API publishing. But nothing lasts forever, and no technology is completely future-proof. The important thing is to pick an approach and maintain metadata. It is always easier to move from more metadata to less than the other way around, so think carefully about what metadata you need now and what metadata you may need in the future.
If you are using REST, consider WADL (Web Application Description Language). It is essentially WSDL for REST. While it is arguably not as easy to use as REST, WADL provides excellent metadata, and some useful tools are available, such as REST Describe & Compile, a WADL editor and compiler. Using WADL may seem like a bother now, but at some point, whether in 5 years or 15, you will have to transition to a different format. Having an excellent set of metadata will make that transition much smoother.
Pulling It All Together
Your API can be a tremendous strategic asset to your company, but it pays to plan ahead. Define your metrics, rid your API of cruft where possible, and filter it out where necessary. If possible, stay away from high-overhead techniques like SOAP. Remember that whatever is hot now will likely be eclipsed sooner than you would like, so build in as much metadata as possible. Pay attention to these rules of thumb, create an API with useful calls, and you will be off to a great start.
If you enjoyed this post then check out Mashery.com, the leading provider of API management services.
