API Portals for Employees

05 May 2016
by: Lou Powell

Many companies have stood up API Portals to create efficiency for the discovery, understanding and requisitioning of APIs. The APIM Portal allows them to overcome the time and expense involved with a tightly coupled, human managed processes for on-boarding new API consumers. It also provides the tangent benefit of creating a single catalog of available services offered by the company, so that they can thoughtfully manage the catalog.

APIM Portals typically facilitate three primary functions:

  • Discovery - Finding APIs
  • Understanding - Learning what the API can do
  • Requisitioning - Gaining authorization to use the API

So, how would these functions differ if we were considering an internal audience vs. an external audience?

Discovery

I have not run across many externally focused API Portals that have hundreds or even thousands of APIs available for consumption. Typically it is in the tens or just a few APIs with dozens of endpoints. The number of APIs these sites have to display is visually manageable. Portals typically contain logical categories and then lists of APIs with descriptions of the API's purpose.

When searching for an API inside an enterprise that has hundreds, if not thousands of APIs there are new challenges. There is a need to rationalize the data against a common taxonomy and vocabulary so that services can be easily found. The APIs need to be organized in a way that is intuitively understood by all of the contributing and consuming developers in the enterprise. Effective searching will need to include multi-term, multi-phrase search with the ability to filter search results using facets and common tags.

Understanding

In an externally facing API Portal, understanding for an endpoint includes the purpose of the endpoint and the method, expected behaviors, descriptions of request and response attributes and any business rules that need to be understood to use the API. Many portals give the developer the ability to run simple API test to better understand the API response based on different requests.

Usage inside the enterprise will be similar for developers who are wanting to consume your API. There is another opportunity though for developers wanting to build new APIs: Education. Wouldn't it be great for an internal developer to be able to find an API that looks like one they need to build and see what software or data design patterns were used to create the API. It would also be really helpful and save countless effort hours if they were able to learn what didn't work and why.

Requisitioning

Requisitioning inside the enterprise needs to work pretty much like it does outside the enterprise. It is important that there is a single methodology for managing and enforcing API governance. There are big benefits to being able to manage approval and consumption of all APIs the same way.

The developers inside the enterprise that are going to be consuming APIs are likely the same folks that will be building and contributing APIs for consumption. It makes sense to facilitate the entire API life cycle from a single place.

To accomplish this there are two additional areas of need for the internal portal:

  • Education
  • Publishing

Continuity in design and presentation for APIs has the same adoption and ease-of-use benefits inside the enterprise as it does outside. There is a need to educate developers on how to build APIs that are presented and behave in a consistent manner. Your documented policies and procedures might include topics like vocabulary, definition document usage, ReSTful design standards and practice, error reporting standards, URL structure, data security, requisitioning security, etc. The point of these processes is not to be dictatorial, but to establish standards that will expedite the delivery of a consistent product. However, don't be too dogmatic. Be open to new perspectives and continuous improvement.

The portal could also be used to educate the developers on your API SDLC, what tools are available and where and how to get them. Allowing the developer to make request for keys and download tools would be a huge convenience.

Publishing

Publishing inside the enterprise is not the same exercise as outside the enterprise. First there is the volume difference. And second there is the management of the API as a product vs an asset.

APIs represented in the external portal are products offered by your company. To get the most value from them, you must gain adoption. And adoption is all about the user experience. Exceptional API Portals have very well designed and documented APIs.

APIs used inside the enterprise are assets. You still need to create documentation that will allow the AI to be easily requisitioned without assistance. But, it will clearly require less polished documentation and presentation considerations than publishing APIs in the portal for consumption by developers outside of your company. And ideally you want to create a process that allows the developer to simply create sufficient documentation. Establishing a definition standard like Open API and requiring a minimum level of help documentation might be all you need.

Consumption of internal and external APIs are important. But a product requires branding and marketing considerations for every aspect of the consumer experience. An internal API asset needs to be well designed and easy to find.

The portal could also provide forms and workflows to marshal the process of getting new APIs published internally. Creating these self-service processes to decrease collaboration and increase speed to API consumption will make your program much more successful.

Those are my initial thoughts on how the API Portal may look different inside the enterprise vs. outside. I would love to hear your perspective.