Why mobile app developers struggle to use poorly implemented APIs

Every mobile application developer has had that “I need data” conversation with a customer who eagerly responds, “We have APIs.” The first reaction is usually a guttural ugh! “We have APIs” usually means that the company has a ReST web service that is securely nestled deep in the enterprise behind a reverse proxy and no documentation. It also means that there is a very arduous journey ahead to gain access to this precious resource and then slowly peel the onion of the API black box back to discover its behavior.

It doesn’t have to be this way!

This is the reason why there is such a movement by companies to build true API programs.

In order to create a great developer experience (DX) in consuming your data you need to consider the following hallmarks of a mature API program:

1. Self-service discovery
2. Explanation of your API consumption contract
3. Explanation of API context
4. Thorough documentation of API method functionality
5. Simple and fast requisitioning

Self-service Discovery

The Utopian follow-on answer to “We have APIs” is “just go to developer.mycompany.com and register for an account.”  This is what we all really want. Point me at the documentation and let me run. API portals are becoming increasingly popular. Not only for the developer experience, but they are also becoming visual indicators of a company’s digital maturity. Your developer portal needs to be designed and considered like any branded, external facing website. The content needs to be well organized and easy to navigate or search and find what you are looking for. Be sure to consider the business processes that stand behind granting access to your portal to allow developers fast access.

Explanation of Your API Consumption Contract

Developers go crazy when your APIs are inconsistent or do unexpected things. Here are some considerations for setting the stage for successful use of your APIs:

1. Explain how you authenticate APIs
2. Make sure there is consistency in attribute and object naming and definition
3. Let developers know how and when you version your APIs
4. Use global Error messaging in all of your APIs and be directive in how to resolve the error
5. Explain the process for how your API will be sunset

Explanation of API context

Good documentation of an API method or endpoint is great, but developers really need to understand the context for how the API is being used. Be sure to answer the following questions:

1. Is there prerequisite data required?
2. Is this API a step in a larger workflow?
3. Does this API orchestrate other endpoints?
4. Is it important for the developer to know how often the data is refreshed?
5. What is the SLA on availability for this API?

Be sure to answer these questions on your portal and update it to answer new questions as they arise.

Thorough Documentation of API Method Functionality

Definition documents are great! But in order for them to be effective for developers (other than the ones who wrote the code), they need to be complete. Or at least complete enough to be helpful.  Be sure to define your objects and attributes using as many properties as apply. Put good descriptions on everything. Provide example method calls and give the developer the ability to test the calls on your portal. Doing these simple things will accelerate developer understanding.

Simple and Fast Requisitioning

Once the developer finds the data they are looking for, understands how to use it, understands how it behaves, and tests it, they want to gain access to a testable service quickly to start using it. It is important that the process for requisitioning access to data for testing is a low bar and can happen very quickly. If the access request for production APIs is more stringent and takes a little more time to complete workflow approvals, that is understandable. Just don’t make that the low bar for accessing testable services. Let developers get started simply and quickly.

I would liken great APIs to great dining experiences. Great dining is NOT only about the food. It is just as much about the environment, the service, how well the food is described in the menu, how attentive the wait staff is, and how well the staff is able to explain what’s in a dish so I can ultimately decide if that’s what I want. It is about the preparation and the presentation.

So go to work and serve up great API experiences for developers.

Written by our friends at Vanick.

If you need API management or assistance implementing Sitecore or Sharepoint, contact them!