How fit do you need to be?
How fit does your API need to be? It may not be the case that your API needs to be “fit” enough to compete in the Olympics but running in a local 5km may be good enough.
The point is that not all APIs need to get to the “Olympic” level below, because very often that simply would not be a reasonable investment. You need to hit the sweet spot of generating as much value as possible with the right level of investment.
As previously described by Erik Wilde in his great blog and video on APIs classification, APIs can be grouped into three categories: Private, Partner, and Public APIs:
- A Private API is consumed within an organization and is not intended to be exposed to consumers outside of the organization.
- A Partner API is consumed by partners of your organization, meaning that there is an established relationship and some framework (often some form of contractual agreement).
- A Public API is intended to be consumed by anybody interested in the API and does not depend on or establish a close relationship; the goal is to make consumption easy and to attract as many consumers as possible.
Private APIs
For Private APIs, a minimalist level of fitness (couch to 5k) can give you a good enough ROI (Return on Investment). So, if you make APIs coherent, findable, and reasonably documented, maybe that’s “good enough.”
Partner APIs
For Partner APIs, you will need to increase your level of fitness and become a marathon runner. You will have to expend a bit more effort to make sure that your APIs work for your partners.
This effort should cover all aspects included in the private tier (coherent, findable, and reasonably documented), but you must make sure that you hit the level of partner usage that you want for this API.
If you’re not there, you must invest a bit more. This could be in API Design, but it also could be in the marketing of the API.
Public APIs
For Public APIs, your level of fitness needs to be approaching Olympian. The threshold for “coherent, findable, and reasonably documented” is different:
- Coherent represents “what developers expect to find these days,” so aligned with current technology trends.
- Findable should be more than “we have a web page somewhere.”
- “Reasonably documented” might turn into a much bigger exercise of producing truly outstanding API documentation with examples and SDKs and maybe even sample applications in GitHub repos.
API Fitness matrix
As with the human body, there are various muscles that can be developed to attain different levels of fitness. Below is a table of API “muscles” which depending on the needs of your API could be developed and enhanced to achieve API success.
Even if your API is public, you may not need to hit Olympian for all areas—it’s a balance and tradeoff between the cost to achieve and the podium placement of the API.
The same is true for Private and Partner APIs—it just may not be worth the cost to enhance the muscle.
Couch | 5km | Marathon | Olympian | |
Why does the API exist? | Overview of API available | Overview of API available Use cases identified | Overview of API available Use cases identified Targeted personas identified | Overview of API available. Use cases identified. Targeted personas identified. Success criteria identified and tracked. |
API-First Process | Reviewed by R&D team | Reviewed by R&D team. Reviewed by Product Manager. | Reviewed by R&D team. Reviewed by Product Manager. Reviewed by internal SMEs (Subject Matter Experts). | Reviewed by R&D team Reviewed by Product Manager. Reviewed by internal SMEs (Subject Matter Experts. Reviewed by external users/ customers. |
Onboarding Measured in time to onboard for a first-time user | Time to onboard ~60 mins. Onboarding to use APIs takes time and may involve installing test systems. | Time to onboard ~30mins. | Time to onboard < 10 mins Self-service onboarding available with the API documentation. | Time to onboard < 5 mins Self-service onboarding available with the API documentation. |
API Lifecycle | API is versioned. | Semantic Versioning. Change log available. | Semantic versioning. Change log available. Deprecation period adhered to. Sunset support. | |
Security (Authentication) | Not for negotiation—Standards-based following best practice. | Not for negotiation—Standards-based following best practice. | Not for negotiation—Standards-based following best practice. | Not for negotiation—Standards-based following best practice. |
Documentation | Overview | Overview Methods summary. | Overview Methods summary. Parameter descriptions. | Overview Methods summary. Parameter descriptions Response codes. |
Examples | None | Quick start guide. | Quick start guide Samples/Cookbook Code snippets. | Quick start guide. Samples/Cookbook Code snippets. Full SDK Postman Collections. |
API Guideline Adherence | Valid syntax. | Passes API Linter. | Some guideline adherence. | Full guideline adherence. |
Developer portal | Available but not bound to endpoint. | Available in the catalog and can be called. | <probably should have something here, or copy the value from the previous column> | Available in the catalog and with all supporting assets available. |
DevX Measured in time to perform post-onboarding | ~60 mins to make a single API call and process response. | < 30 mins to make a single API call. | < 60 mins to attempt use case. | < 30 mins to attempt use case. |
Experience | Uses own nomenclature | Shares vocabulary with other APIs. | Similar objects/concepts that require little massaging between successive calls. | Unified with other APIs and can easily be called as part of a successive chain. |
SLA/Availability | Best effort | 99.0% | 99.5% | 99.9% |
Discover more information on different types of APIs.
Read the white paper and learn how APIs are the key that unlocks modern IT and digital success.