Best Practices for Service API Definition

Share the article!

In recent days I have come across a couple of interesting articles on the web on how to define service APIs.

The first one titles “Web API Documentation Best Practices” from ProgrammableWeb. The author writes about the importance of good documentation in that it encourages and keeps developers interested in the service and also helps reduce support costs. The article describes some basic areas that should be covered by documentation such as having an overview, a introduction section, sample code, and references. The article further recommends the following best practices:

  • Auto-generate Documentation
  • Include Sample Code
  • Show Example Requests and Responses
  • Explain Authentication and Error Handling

Mark Blotny wrote that “Each Application Should Be Shipped With a Set of Diagnostics Tools. He writes that developers typically have limited access to the production servers. However in the event that something goes wrong, developers require the capabilities to perform an investigation in reasonable time to identify to uncover the causes of the problems. He writes that a service api should have the following:

  • Each integration point should include a diagnostic tool.
  • There should be accessible logs for each call to an external system.
  • Service peformance data should be accessible by developers.
  • All unexpected errors should be logged and easily accessible.

Finally there is an article by Juergen Brendel who wrote “The Value of APIs that Can be Crawled“. He writes that a service API should be designed such that it can be discovered via a crawler. Although this requirement is commonsense for anyone concerned with SEO, it unfortunately isn’t quite common for developers of service APIs.

The notion of a decentralized index who’s data is populated by crawlers should in fact be key technology component of any Service Oriented Architecture (SOA). Surprisingly however, despite the success of search engine companies like Google, this component is absent in most of all SOA stacks I have seen. In SOA stacks, there is a notion of a service directory, in most implementations the assumption is for a centralized service and the onus is on each service to register and provide appropriate and current information to the directory. It appears to be logically the same thing, however what scales in practice is the decentralized index/crawler and not the centralized directory.

These three articles show that there is in fact value in providing service functionality that goes beyond the documented functional requirements. There is in fact research that I came across that documents this in a more comprehensive manner. Here are the property groups that a service may provide:

  • Temporal
  • Locative
  • Availability
  • Obligations
  • Price
  • Payment
  • Discounts
  • Penalties
  • Rights
  • Language
  • Trust
  • Quality
  • Security

I love lists exhaustive lists like this because it reminds me of what I may be missing. Speaking of which, it reminds me that Web Services Modeling Ontology (WSMO) has something formal along similar lines. In fact, if you really want to go into the deep end with service contracts, you can read this.

It is interesting how this non-functional attributes (i.e. ilities) align well with the idea of Aspects Oriented Programming and can be implemented in a proxy like infrastructure. That is in fact what it appears that existing “API Management” firms (ex. Mashery, Sonoa, WebServius, 3Scale) appear to provide. Here are some examples of the features that these API Management firms are offering:

  • Reporting, Analytics and Visualization dashboard.
  • Traffic management and rate-limiting
  • Security, Access Control, Authorization.
  • Mediation – Protocol Bridging.
  • Monetization
  • User management and provisioning. Self service provisioning.
  • Community management. Portal, Access key management, FAQs, Wiki
  • Scalabilability. Clustering, Caching.
  • Threat Protection – Denial of service attacks.
  • Versioning
  • Operations Management. Root cause analysis. Logging.

Share the article!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>