Design

Thriving Among the APIs

By Asanka Abeysinghe and Sumedha Rubasinghe, December 15, 2014

You're about to start work on designing and publishing your product's API. Now what?

The API economy is enabling companies to connect and collaborate with internal team members, customers, and partners, and creating new models of monetization, agility, and efficiency. There is tremendous opportunity for developers to play a central role in this fast-paced evolution, but there are also pitfalls. This article seeks to provide guidance on implementing effective, road-tested best practices that enable developers to thrive in the API economy.

Defining a Good API

To begin, a developer needs to ascertain the key elements that determine a "good" API. Typically, an API should employ basic REST principles and be able to leverage existing services or service platforms. It can be enhanced by using techniques, such as HyperMedia, to efficiently handle larger amounts of data and ensure compatibility for any delivery channels, including Web, mobile, and devices.

A good API is discoverable and easy to consume from mobile devices and the traditional Web. It requires fewer interactions to offset mobile latency issues, and it considers the entire Web API design, whether it's device- or Web-based. An effective API should be stateless and as simple as possible, enabling ease of use and adoption with easy scalability.

Creating API-Ready Services

To enable successful development of APIs, developers first need to convert business capabilities into services. Legacy systems must be converted as well. Turning business capabilities into services alone is not enough; they need to be further converted into API-ready services. This includes the functionality, binding, security, data model, and message format. It is also important to create new services that meet the requirements of new business capabilities, thus responding to the demands of the API economy.

To help pull together multiple internal services, developers can employ the concept of service chaining/orchestration. To this end, two specific considerations are capabilities and payload:

Capabilities: APIs are required to provide capabilities based on the demand from consumers; however, backend services might not directly address these requirements, thereby creating the need to aggregate the backend services.

Payload: APIs may require different payloads, and a single service may not provide all the information required to build a given payload. In that case, it may be necessary to call multiple services.

Legacy systems also need to be reviewed to ensure they are not stateful, overly rich, or complex; do not contain hyperlinks; and are free of perilous, non-mobile-friendly protocols. For this, developers may need to write and convert legacy elements in a REST-friendly manner by pulling together multiple internal services.

To leverage the opportunities, developers should identify loose ends and adopt approaches to bridge these gaps, notably through coding and using an enterprise service bus (ESB).

Use of coding to make up for the differences is one good approach. However, this method provides very little flexibility and requires recompilation/deployment for a change to be implemented. This concept is encompassed in wrapper services.

Use of an ESB can provide a declarative approach to bridge the gap between API needs and existing legacy implementations. For example, exposing the Financial Information eXchange (FIX) protocol through HTTP can be as simple as following through an ESB. In this case, the ESB is used as the API gateway within an API management solution. Exposing a SOAP service over JSON through an ESB can be achieved through simple configuration as well.

Bridging Stateless and Stateful Worlds

Bridging the gap between stateless and stateful worlds presents a particular challenge. APIs are exposed as stateless interfaces; however, if the backend implementation requires statefulness, such an implementation should be possible. One approach is to create a session mapping layer between the API and backend service. This mapping layer can be implemented using the NoSQL layer or a distributed caching layer. These technologies will support the creation of a replicable and scalable persistence layer for application sessions.

A Well-Designed API is More Than Code

It is not enough to have a clean API, a well-designed one also should include some or all of the following characteristics:

Intuitive operation/resource definitions

API documentation

Correct choice of protocol style: Increasingly, REST is the style preferred over others

Support for modern data formats: JSON has taken the lead, followed by XML and CSV

Standard authentication and authorization support

The availability of ample documentation and samples alongside the API will make the developer's life a lot easier and enable easy adoption as well.

Figure 1: Swagger Style Documentation.

One effective approach is the Swagger style of API documentation. A default Swagger-based skeleton is created when an API is created, and there's a in-built editor as well.

Another essential element is API keys, which ensure that API consumption happens in an easy, secure manner. Moreover, API developers will be aware of who is accessing the APIs because each API will include these keys.

Versioning, too, is helpful to developers because it allows them to make changes and improvements incrementally, as well as add capabilities. An absence of versioning will hamper new releases of an API as well as efforts to change an existing version. From the API consumer's perspective, versioning lets the developer choose whether to stick with the current version, and also determines when it is time to move to a new version.

In addition to versioning, an API needs to be highly available so that a developer will be notified in the event of an issue, enabling prompt action to be taken. This is also key to identifying and detecting any misuse of APIs at an early stage.

Driving Adoption: The API Store

Having a clean, well-designed API is a strong start, but it is not sufficient if you want to become a key part of the API economy. Even though it might not be traditional developer territory, there is a need to "sell" the API to other developers to leverage benefits.

A good example of such a scenario is an API store, which enables enterprises to create a graphical experience similar to the Android Marketplace or Apple App Store, which makes it easy for internal users, customers, and partners to access APIs.

A good API store lets developers browse APIs by provider, tags, or name; self-register to the developer community; subscribe to APIs and manage those subscriptions on a per-application basis; and browse API documentation or download helpers for easy consumption. At the same time, enterprise IT organizations can manage subscriptions on a per-developer level, as well as offer subscriptions at different service tiers based on expected levels of use. Ideally, a commercial API management offering should be customizable enough to let organizations create skins for the API store that align with their corporate or product branding.

Portals are a great place for discovery because they help users find APIs exposed by various organizations to be used by developer communities. An API management solution should offer some form of API portal. For reference, we've listed below some popular API portals:

API developers can collaborate with API users by employing forums, comments, and social media. To this end, the API store provides many of these collaborative features, helping users to communicate, share comments, and rate APIs. This enables users to be informed about the popular and best-rated APIs and share these findings. In other words, this portal offers some element of advertising of APIs to help you take it to the next level.

The self-signup to an API from the API store or portal can happen in two ways: controlled and public. Controlled refers to a managed process whereby a developer signs up but goes through an approval process before access is enabled. Some APIs might be restricted as well. Public access is unmanaged and allows a developer to self-sign, lookup APIs, and subscribe to them.

Monitoring APIs for Service and Monetization

Monitoring and usage are key to ensuring better service from APIs. To this end, developers need statistics to determine certain elements such as usage, user behavior, possible enhancements, and billing metadata, among others.

Furthermore, if organizations want to charge for the APIs, this would need to be supported by the availability of monetization data. The information provided by monitoring can provide insights into setting subscription costs for different levels of service, as well as gaining visibility into subscribers' daily usage. Monitoring of spikes in use may lead to temporary throttling, while regularly high levels of use could lead to a suggestion for the subscriber to upgrade to the next level. A subscription can be based on usage, or it can be time-bound with periodic renewals (such as one year, two years, etc.).

Broadening the Developer's Role in the API Economy

Broadening access to APIs has created an economy that's exploding with new business development, prompting modern enterprises to move steadily from being software-enabled to being API-enabled. Similarly, ecosystems of APIs also are creating opportunities for new business ventures. Developers and software architects who think beyond an API's code to supporting its entire lifecycle through a store or portal, API management, and effective monitoring will be well positioned to thrive in the API economy and capitalize on these opportunities.

Asanka Abeysinghe is WSO2 vice president of solutions architecture. In this role, he spearheads the company's customer-facing technical tasks and oversees the solution architecture and technical sales functions. Sumedha Rubasinghe is Director of API Architecture at WSO2. He has contributed to the successful implementation of data, SAP and repository-based integration projects, as well many WSO2 QuickStart development consulting engagements.

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task.
However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Video

This month's Dr. Dobb's Journal

This month,
Dr. Dobb's Journal is devoted to mobile programming. We introduce you to Apple's new Swift programming language, discuss the perils of being the third-most-popular mobile platform, revisit SQLite on Android
, and much more!