Application Programming Interface (API)

What it means

An API exposes a deliberate set of operations, inputs, outputs, and failure behavior for use by application code. It separates what a consumer may ask for from how the provider performs the work. APIs include library functions, operating-system interfaces, device interfaces, and network services; a web API is only one common subtype.

How to calculate it

API is an interface concept, so there is no universal API formula. Evaluate a particular API with operational measures tied to its service objective and consumer journey rather than inventing one composite score. Reliability | Successful eligible requests divided by eligible requests | Define which client and server errors belong in the denominator Latency | Distribution of response time, commonly p50, p95, and p99 | Segment by operation and payload size Adoption | Active integrations, successful first calls, and time to first value | Shows whether the contract is usable, not merely available

What counts / what does not

Treat the documented contract as the decision boundary. Internal code and implementation details are outside that contract unless they are explicitly exposed. Include | Callable operations, parameters, schemas, authentication requirements, responses, errors, limits, and compatibility promises | These are the consumer-visible agreement Exclude | User-interface screens, undocumented database structure, private helper functions, and internal deployment topology | They can change without being part of the API State explicitly | Protocol, versioning policy, rate limits, idempotency, pagination, deprecation window, and support ownership | Ambiguity here creates integration risk

What moves the number

A useful API is shaped by contract clarity, predictable semantics, security, compatibility, observability, and developer experience. Contract design | Stable names, schemas, and error behavior reduce consumer guesswork Lifecycle discipline | Versioning, deprecation notices, and migration paths prevent surprise breakage Operational quality | Authentication, authorization, quotas, retries, idempotency, and tracing make integrations safe to run Consumer feedback | Documentation gaps, support cases, and failed first calls reveal friction the specification alone cannot show

When it helps

Defines which capabilities other teams, partners, or customers may depend on. Turns compatibility and deprecation choices into explicit product and operational commitments. Lets security, reliability, and support owners review the same consumer-facing contract.

• Defines which capabilities other teams, partners, or customers may depend on.
• Turns compatibility and deprecation choices into explicit product and operational commitments.
• Lets security, reliability, and support owners review the same consumer-facing contract.

How to use it

• API means application programming interface, not a synonym for any website or backend.
• HTTP and REST are possible implementation choices; neither defines the entire API category.
• The contract must describe success, failure, and change, not only the happy-path request.
• Measure the consumer outcome and operating behavior separately.

Decision cautions

Do not publish an interface before deciding who owns compatibility and incident response. A documented endpoint can still be unsafe if authorization is checked at the wrong resource boundary. Automatic retries can duplicate non-idempotent actions unless the contract and client behavior agree. A breaking schema change can damage consumers even when the provider deployment itself is healthy.

• A documented endpoint can still be unsafe if authorization is checked at the wrong resource boundary.
• Automatic retries can duplicate non-idempotent actions unless the contract and client behavior agree.
• A breaking schema change can damage consumers even when the provider deployment itself is healthy.

Read with

Pair technical health with evidence that consumers can integrate and recover from failure. Availability and latency | Show runtime behavior against the service objective Error mix | Separates invalid requests, authorization failures, throttling, and provider faults Time to first successful call | Tests documentation, credentials, examples, and onboarding together Deprecated-version traffic | Shows migration exposure before an old version is retired

Example

A retailer exposes an order-status API to shipping partners. The contract accepts an order identifier, returns a defined status schema, requires partner-scoped authorization, and uses a consistent not-found error. The team documents a rate limit and a 90-day deprecation window, then monitors successful first calls, p95 latency, authorization failures, and traffic on old versions. When a new delivery field is added, it is optional, so existing consumers continue to work.

Compare with

API | Software-facing contract for requesting capability or data | Can be local or remote User interface | Human-facing interaction surface | Optimized for people rather than programmatic calls Protocol | Rules for communication, such as HTTP | An API may use a protocol without being identical to it SDK | Language-specific code that helps call an API | A convenience layer, not the underlying contract API documentation | Human- and machine-readable information about calls, inputs, responses, errors, and changes | Describes how consumers use an API; it is not the running implementation

Common mistakes

• All APIs are REST APIs. Libraries, operating systems, devices, RPC services, and other interfaces also expose APIs.
• An API is just an endpoint URL. The contract also includes operations, data shapes, permissions, errors, and lifecycle rules.
• A generated specification guarantees a good integration. Consumers still need coherent semantics, examples, support, and reliable operation.

Frequently asked questions

Sources