agility continued: (b) Web API -ing

continuing from the previous post, after ESB-ing and having the requirements in place, we can see the possible usage of web APIs.

(b)Web API-ing

In general, there are various sides to view the same things. On the developer’s side of the world, were things should be more binary, APIs are the usual way to make computers talk together and help to build various layers of an application or application’s components. They can help in building business layers on top of other business layers on top of etc. On the other side of the world, the user’s or client’s side, where things tend to be less binary, APIs represent a two-way strong strategic tool (”two-way” because releasing an API impacts both the original developers of a web application and third-party developers building a third-party web application).

Let’s start scoping with the third-party developer’s view, which might be you in the (common) case of using an existing API, lets say an Open Source API. The reason of using an API means that you are willing to programmatically get data out of a website or another web application in general. For simplicity, lets stick to the website (meaning that we may have a web exposition of infos/attributes etc from a legacy system). For any third-party web developer, using an API is great because it allows to:

• backup existing data: say you are not so confident in the future of website (application) you need to connect to, you can programmatically backup your data stored in there through the API
• leverage existing data and, for example, display it in a more innovative way: You could build a great third-party application relying on the website (application)’s API and provide an alternative way of exposing (front end) data (e.g. showing an interactive map with the members’ names updated in real time)
• catch new users: say you have done with the building of your app, then (at least!) a percentage of original website (application) users will be interested in it and will start using it
• unload some server resources: some web services do things well and fast, so why bother reinventing the wheel and consume server resources? For example, you could save storage for your pictures by using Flickr’s API (or Amazon S3’s), you could create charts using Google’s Chart API etc.

If we look at things from website (application) point of view, releasing an API is a strong signal and should be part of a well-thought strategy, aimed at:

• extending reach by bringing in new users from third-party apps using his/her API (there’s a mutually beneficial exchange of users between the original application and the third-party application, each one becoming a new entry point for the other)
• becoming a local expert: this is a really important point, because simply, releasing a clever API can erase competition from your niche
• fighting against web scraping: third-party web developers would now have an official and documented way to get data out of an application (of course they can still keep on scraping your web pages but releasing an API greatly simplifies their lives and encourages them to keep to the straight and narrow)

Becoming more practical, you can communicate the above simplified view in your proposal to the client, denoting that:

• APIs can be among a company’s greatest assets

® Customers invest heavily: buying, writing, learning

® Cost to stop using an API can be prohibitive

® Successful public APIs capture customers

• Can also be among company’s greatest liabilities

® Bad APIs result in unending stream of support calls

• Public APIs are forever – one chance to get it right

API design (or what to look in yours candidate for usage APIs)

When releasing an API, developers should follow a comprehensive checklist to ensure third-party developers will start using it smoothly. In particular, it is essential to:

• offer the widest range of protocols: some developers love REST, so you have to release a RESTful version or your API; some other developers can’t live without XML-RPC so open a XML-RPC access to them; some other have existing libraries built for SOAP so release a SOAP API; some other love JSON so build a custom “JSON-RPC” API for them etc.
• document all the API’s functions for every protocol: yes, this is a huge work and this is were you will spend most of your time; documentation is key and the clearer it is, the more developers will use you API. Check out Flickr’s or Facebook’s APIs documentation: they’re real jewels for web developers, filled with substantial code snippets helping them to get quickly started with the API.
• version your API: remember that once released, an API is forever. This means you can’t go backwards and change existing functions in your API because this would be a disaster for third-party applications built upon it and, therefore, for your users and your reputation. With an API, you can only go onwards. So it is extremely important to explicitly define versions for your API, for example by inserting version numbers right in the URL
• make it secure: web APIs have to be secure, both technically and strategically. Technically because accessing the data should happen the way it was meant to be without disrupting existing processes on the server or causing mess in the database. Strategically because releasing a web API is opening a documented door to the very heart of your content. An easy way to enhance security for your API is to release API keys: third-party developers have to request a key (usually a hash-like sequence of digits and letters) and then explicitly show this key in every single call made through the API. Doing so allows you to better monitor traffic and usage of your API.
• anticipate traffic surge: releasing an API means facing traffic spikes and, if everything goes well, facing a global increase in the load. It is crucial to anticipate this and avoid outages.

Again, in a practical mood, you can communicate that you are going to provide:

• Service Provider Interface (SPI)
  → Plug-in interface enabling multiple implementations, e.g Java Cryptography Extension (JCE)
• Write multiple plug-ins before release
  → If you write one, it probably wont support another
  → If two, it will support more with difficulty
  → if three, it will work fine

Protecting web property

Here is a simple schema to better understand what’s going on when releasing an API (as graphed here) :

In this example, website 1 is the usual interface developed to display the data (for example: website 1 is the website (application) that you intent to connect with). Website 2 is a parallel website accessing website (applications)’s data but not developed by the vendor of website (application). For example, it’s an aggregator designed to consolidate profiles from different online communities. For website (application), releasing a web API is interesting to extend its reach and bring in new users (for example, users of the aggregator service at website 2 who didn’t know about the website (application) until they discover some of its members) but it also means organizing a documented data leak towards third-party apps, hence the need to focus on technical and strategic security.

From the practical point of view, you should

· Minimize Accessibility of Everything
→ Making classes and members as private as possible
→ Public classes should have no public fields (excepting constants)
→ (therefore) miximization of information hiding
→ Allow components modules to be used, understood, build, tested and debugged independently

… and of coarse always having in mind that:

· API (must) Coexist with Platform
→ obey standard naming conventions
→ avoid obsolete parameter and return types
→ mimic patterns in core APIs and language

· API friendly features
→ Generics, varargs, enums, default arguments

· API avoids traps and pitfalls
→Finalizers, public static final arrays

· Intelligent Exception Design
→Throw Exceptions to Indicate Exceptional Conditions
don’t force client to use exceptions for control flow
private byte[] a = new byte[BUF_SIZE];
void processBuffer (byteBuffer buf) {
try {
while (true){
buf.get(a);
processBytes(tmp, BUF_SIZE);
}
} catch (BufferUnderflowException e) {
int remaining = buf.remaining();
buf.get(a, 0, remaining);
processBytes(bufArray, remaining);
}
}
conversely, don’t fail silently
ThreadGroup.enumerate(Thread[] list)
→ Favor Unchecked Exceptions
Checked – client must take recovery action
Unchecked – programming error
Overuse of checked exceptions causes boilerplate
try {
Foo f=(Foo) super.clone ();
….
} catch (CloneNotSupportException e) {
// this can’t happen, since we’re Cloneable
throw new AsserionError();
}
→ Include Failure-Capture Information in Exceptions
Allows diagnosis and repair or recovery
For unchecked exceptions , message suffices
For checked exceptions, provide accessors