API Basics

How fit is your API? 

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.

One size does not fit all

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:

  • Private API is consumed within an organization and is not intended to be exposed to consumers outside of the organization.
  • 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).
  • 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 

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.

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
/conventions.

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.