Best Practices for an API Portal

Listed below is a list of metrics to manage Microservices and API initiatives



With the adoption of APIs into organizations, it’s clear many desire to enable self-service capabilities for their API consumers. The best way to achieve this with today’s technology, is through an API portal.

Below are some important Best Practices for APIs entering an API Portal. I created a 58 point checklist for APIs to follow to govern entering an API Portal, but below are some immediate Best Practices. Please email me if you would like a copy of the API Portal Checklist, or if you would like me to present it to your team.

1) Make sure API Providers have clearly defined the functional and technical definition of the API. Sounds trivial, but its important.

2) Adopt Swagger and Open API spec, so all APIs can be easily and consistently managed in the portal

3) Define your Security Model for internal and external facing APIs. Will it just be Client ID/Secret or will you have an OAUTH2 Policy?

4) Mandate a Data Dictionary before APIs enter the portal. Consumers need to understand field level definitions.

5) Understand if the APIs are for Systems of Record vs. Intermediary Systems.

6) Identify sensitive data, so it can be properly protected through security and encryption tehcniques.

7) API Providers must have a TEST environment for your portal to have a “Try it Now” feature.

8) API Providers must share their version control process.

9) Also, their Change Management (and communication) process.

10) How are the API providers doing logging, auditing, and Analytics? Please have them share this before entering the Portal.

11) Do they have SLA’s on their APIs for response times and availability?

12) What about constraints on # of requests, concurrent consumers

13) What is the API provider’s Operations and Support model?

14) How does API providers alert consumers?

15) What are the API Providers quality assurance techniques? How does the Portal know the API has been tested for functionality and performance? Can the API Provider share their testing results?


Jordan Braunstein, CTO