This is another in a series of exploratory questions that someone might ask when kick-starting an API strategy for your company.
How do you make it easy for users to access your business assets and capabilities using APIs?
A word that is typically used when people start talking about getting access to APIs today is “frictionless”. Opening your APIs so that users (usually developers) can get access to them is an important part of your API strategy. You want people to be able to sign up, learn how to use your APIs, and be able to access them in the most efficient, enabling way possible – creating this frictionless interaction between developers and your business.
Self-Serve
In 1947 the first self-service gasoline station opened in Los Angeles. It still required attendants to be present at the pump to take money and reset the pump back to zero after a customer had finished pumping gas. The “newfangled” process had some success but frankly businessmen adopted it because it saved them money (because they could use less staff at their stations) not because it was of any real help to the customer. In 1964 came the next innovation: remote access to the pump. Now a single attendant inside the store could control the pumps making for a much more streamlined process for the customer to pump their own gasoline and not have to wait for an attendant to do it (of course now the customer had to go inside to pay the attendant.) 1973 saw the next evolutionary step of pay at the pump. Over time all these came together to make self-service an obvious choice for gasoline stations to increase sales and provide a better experience for the customer.
Today’s API management solutions use this same self-service idea as the first steps to engage its potential users. People can sign up and get access to a company’s APIs typically through a quick and easy form and then access can be granted in a couple different ways. A company can configure their API management solution to give the user some basic type of access immediately, for example access to a subset of the APIs available and some restricted form of access like a maximum number of calls per day for free. They might have a “pay-at-the-pump” model where the user can pay for high-level access (more APIs or more calls per day.) A company can also have an approval model where the request goes into a queue so that it can be reviewed before the approval is given with the click of a button. The goal is to make the process of getting access to the API as easy as possible for the user so they can start developing.
Getting Started
It should be easy to learn how to initiate an API request and interpret the API response. If you’ve read anything at all about APIs, you already know the REST protocol (based on standard HTTP) and JSON data formats are prevalent for implementing APIs. This is true based on lots of feedback from users and industry experts who say that this is a straightforward methodology to provide access to the APIs. That said, there are certainly other protocols and data formats that can be used with SOAP and XML long being popular as well. Different situations might call for different approaches. For example SOAP might be used if you want to take advantage of the self-validation of an XML payload but overall the people have spoken and REST/JSON are definitely deemed a good choice with good reasons to support choosing it (and there is work to extend the JSON specification to provide self-validation and other enhancements which some say provide some of the positives of SOAP/XML without the perceived negatives.)
Using the APIs also includes having access to great documentation and examples. I’ve been in many projects and documenting work can be a tedious and time-consuming task. At worst, it gets pushed until there isn’t any time to do it properly (or at all) or it is done but not maintained and is quickly out of date. Up to date documentation and examples of how to use your APIs is a crucial effort for a successful API program. Most API management solutions have support for various documentation standards and tools that are emerging in this space. Swagger, RAML, WADL, and others (proprietary and industry standard) are tools available to accomplish this. API management vendors also (generally) offer developer portals to support access to this information and the ability to run APIs to provide examples of its requests and responses. Developers are a unique kind of customer and they are vocal when they are expected to use tools with inadequate documentation or missing examples. Remember: You want them to be fans, not just users.
Community and Support
Support your API users by providing them a forum where they can post successful applications of your APIs, discuss problems, and share their experiences with your API platform. Not only does this peer discussion help them, but it will also help you by providing enormously valuable feedback on what’s working and what’s not with your API (developers are famous for telling it like it is…you only have to listen!) If possible, create the opportunities for your API users to gather virtually and (even sometimes) physically through hack-a-thons, meet ups, and conventions. The external people (outside your organization) that are using your APIs are an extension of your company and the internal people (your own employees) who are using the API are the creators and innovators of your company. Supporting a sense of community is just good business.
Turning your API users into fans is a golden opportunity and making it easy for them to get access and learn how to use your APIs is essential when forming your API strategy. Fans don’t just use what you’re offering. They celebrate it and promote it and lift it up to others which is another strong pillar to grow the strength of your API program.
To foster innovation, creativity, and excitement within a solid developer ecosystem you should
- Establish frictionless developer on-boarding for API access
- Create and maintain great public API documentation
- Nurture a collaborative developer community
And this will support a successful API program for your company.
References
“Self-Serve Evolution” by Sarah Hamaker
“Siren: A hypermedia specification for representing entities”
