API Integration Manifesto

Oct 2018 by Neil McKinnon

Advice for building quality APIs

Simplicity Over Functional Overload

Consumer integration is challenging if APIs are overloaded with (unnecessary) functionality. Only release the functionality truly necessary to allow the business to compete.

Don’t Expose Your Privates

Use the best structure for the consumer, not the one that closest reflects an internal (e.g. database) structure. Use consumer-friendly naming conventions for resources and fields. Combine internal resources to produce consumer-friendly structures.

Expect Change But Minimize Breaking Changes

APIs in active use exhibit tougher change cycles than unused ones, causing evolutionary challenges. Where practical, attempt to understand the future usage of an API to minimize disruption internally and externally.

Eat Your Own Dog Food

The only way to truly appreciate a consumer’s perspective is to be that consumer. Internal applications should integrate directly through APIs. Documentation should also be examined for exactness.

Thinking Over 'Silver Bullet Technologies'

Rarely does a new technology offer a silver bullet solution. Quality integrations are built from careful consideration and design. Tools and technologies augment thinking, they don’t replace it.

Simple Consumer Integrations Over Maintainable Internal Code

Internal code quality is important, but the consumer experience should not be impaired solely to satisfy internal qualities (e.g. code maintainability).

Identify Appropriate API Granularity

Quality APIs have the correct granularity principles applied to them. Fine-grained APIs tend to be too “chatty”, whereas coarse-grained APIs may make too many assumptions, hindering flexibility and reuse. Also be cautious that consumers don’t build workflows that break transactional boundaries.

Guidance Over Dictatorship

Guide integrators down the best route by providing them with the tools (e.g. links) to do it. However, also provide the flexibility for integrators to do something differently, without the need for additional consultancy.

Autonomic Over Error Intolerant

Integrators like fault tolerant solutions. Integrators should not (necessarily) be penalized, when making a minor infringement, if common sense rules can be applied.