The first generation of API management tools has been focused on helping developers publish APIs for other developers. Developers are highly successful at publishing APIs, so much so that now there are millions of public APIs available. However, we’ve been less successful at getting downstream developers to actually use our APIs. External adoption of most APIs has lagged greatly behind expectations.
API publishers have learned that there are many facets to driving adoption and usage of their APIs. The next great challenge in API management revolves around one question: How can we make our APIs more compelling to other developers?
Integration is the leading use case for most APIs, and some of the best APIs have common traits that support integration use cases. Four that are proven to boost your API’s adoption are accommodating custom data, providing machine-readable docs, applying rich metadata, and exposing webhooks. These features will increasingly become more critical in driving adoption of your APIs as developers select not only the easiest but the most functional APIs to accomplish integration tasks. Ultimately, these are the traits that increase your API’s rate of adoption because they make life easier for your customers.
Contents
1. Accommodate custom data
SaaS apps make extensive use of custom data objects and custom data fields. Many SaaS apps provide powerful capabilities for users to create, update, and delete custom data, but most of these apps do not provide similar custom data management facilities through APIs. There is a series of steps to take to better accommodate custom data through your APIs, from discovery to field-level CRUD to reaching full CRUD operations for custom objects.
The first step to better accommodate custom data is adding a discovery API that provides the capacity to find all custom fields and objects at an endpoint electronically. Extending your API to provide a robust data discovery capability will make it far easier for developers to accomplish integrations tasks, while making it easy for them to programmatically find the unique data objects and fields in each instance of your application.
The next step in accommodating custom data to provide a complete set of RESTful methods is to enable CRUD operations for the data in each custom object. Enabling your developers to programmatically manage the custom objects like your standard objects will allow true dynamic integration experiences. Integrations are “dynamic” when they allow each integration to be uniquely designed based on the data discovered at the endpoint. Static integrations, on the other hand, are suitable for services with fixed payloads such as cloud storage, payment, and messaging services.
The most advanced means of supporting custom data is to provide APIs that actually create new custom objects and new custom data fields within standard objects. Integration scenarios often require developers to create a new field or object in the application to accommodate custom data from other applications that are being integrated with the app. Developers can create more powerful self-service integration experiences when they can create custom objects without requiring manual intervention through the user interface. Salesforce already has a great set of custom object APIs that demonstrate a best practice case of the ability to do full CRUD through APIs, including the creation of custom data.
2. Generate machine-readable API docs
Machine-readable documentation — the province of Swagger 2.0 and RAML — allows you to define your API in a manner that is easily discovered and understood by both humans and computers with minimal effort. By supporting an electronic and interactive definition, your API can be programmatically parsed and understood, including the full model schema, allowing your API to be integrated more efficiently.
The Swagger and RAML API documentation creators enable applications to ingest a model of an API (like a JSON model schema), then integrate and maintain the APIs — all while minimizing coding. Other benefits include reduced maintenance cost, as updates to your API can be obtained programmatically, streamlining the effort required to stay up-to-date. The implementation of these description languages is still in the early stages of adoption, but Swagger 2.0 is rapidly taking off in the SaaS and API management community. Its adoption is further fueled by the Linux Foundation’s Open API Initiative, which has adopted Swagger 2.0 as its standard API description language.
In fact, the Swagger 2.0 model can automatically generate SDKs for your API and keep them current, which can further accelerate adoption. Of course, many believe that SDKs are a pain to deal with; traditionally, they can’t be maintained and kept updated, as they’re always behind the API definition while they wait to be manually generated and maintained. Machine-readable docs eliminate this annoyance by making it possible to ingest the model schema of an object or resource electronically, and they generate SDKs that are always up-to-the-minute because they’re being generated from your API documentation.
3. Apply rich metadata around objects
Enriching APIs with metadata makes them more easily discoverable by the application developer and enables applications to understand the structure of your API with a richer context, such as the acceptable values for a field. You want the consumer of your API to know everything about your resources and the fields associated with those resources. Comprehensive metadata not only provides information about the structure and context of an object, but also information about consumption limits, which events are available, and other valuable data to guide the integrator.
The richer the metadata, the more easily your API can be integrated from the edition you’re on and insight into the macro (service) level, as well as being privy to each individual object and resource within that level. Metadata describes how to implement APIs per that data, how to call it in detail, and what it supports.
4. Expose webhooks
The majority of integrations requires events to trigger when an action should take place. Unfortunately, few endpoints support webhooks today, and among those that do, too many expose only a small subset of their available resources. Embracing webhooks is a terrific means for accomplishing integration use cases; rather than forcing users to pull your site, you can give them an event that grants access across all of your resources (versus a mere subset).
There are three stages to exposing webhooks: setting them up, addressing their structure, and addressing their coverage. But first, you need to embrace webhooks. Webhooks enable publishers to implement APIs more effectively and synchronize data among multiple APIs. The best APIs give you the ability to create a webhook programmatically, then instantiate.
After your webhook is set up programmatically, you can address its structure. Your webhook structure should be designed to provide as much information as possible. When configuring a webhook, you can choose the events for which you would like to receive payloads. You’ll find an excellent example of an effective webhook structure in the Delighted API.
You can count on developers to seek the most functional and easiest API to accomplish their integrations. If your API can accommodate custom data, provide machine-readable docs, apply rich metadata, and expose webhooks, then it has a much better chance of being adopted externally. That’s because it is a superior API.
[Source: Javaworld]
