Create Great API Designs and Documentation With Integration Across the API Life Cycle
In Forrester's recent API Design and Documentation Report, author Randy Heffner discusses how APIs underpin digital disruption by providing the "building blocks that enable rapid business reconfiguration. But not just any APIs will do - they must be well-designed. API design is the fulcrum that determines how much value one's API strategy creates."
In this report:
- How to build an API Strategy
- Emphasizing business APIs and portfolio management
- Collaborating to design APIs and API Products
- Establishing a product management discipline for APIs and API Products
- Creating appropriately comprehensive documentation for APIs
- Coordinating lifecycles for API design, documentation, and implementation
- Forrester cites digitalML’s product as being differentiated enough to be worthy of special note out of 31 vendors, stating that digitalML takes an expansive view of API design and documentation, providing the broadest set of features for business and technology collaboration around a core design and documentation for APIs and API products.
We've read the report a number of times as well as discussed with our customers. Here's the top 6 takeaways we've gathered.
1. Emphasize business APIs and portfolio management
- Business APIs provide direct access to an organization’s business capabilities without tying API users to specific applications
- A portfolio provides a coherent, consistent set of APIs (and services, events, messages, information models) that are available internally (or externally if you choose) rather than haphazardly building to the point needs of isolated projects
2. Establish product management disciple for business capability APIs and API Products
- API providers should offer, and consumers will bundle, multiple APIs into an API Product. An API Product may combine whole APIs, or only individual operations from multiple APIs
- Manage API Products as actual products – like products, APIs have providers and consumers so treat APIs like products with communities that care about and want input into product futures
3. Agile plus architecture while identifying centers of gravity
- Business led API design doesn’t happen in isolation, but to allow for collaboration you need visibility and a bidirectional heartbeat and prioritization between delivering innovation and unlocking capabilities
- There will be multiple centers of gravity across roles, initiatives and lines of business with different cadences and priorities – collaboration, agility and architecture create the right balance between freedom/speed and the consistency that ensures sustainable business agility
4. Set a lifecycle for API design and documentation within the broader API lifecycle
- The discipline of API Portfolio management provides context for designing individual APIs so that over a surprisingly brief amount of time, an organization can build a portfolio that provides full coverage of their business capabilities exposed through APIs
- This becomes easy and fast when you bake in API documentation, domain-driven design, consistency and governance into the process, so it’s part of the (early & often) effort instead of a bottleneck
5. Use DevOps and continuous delivery to drive automation across lifecycles
- API design doesn’t end once an API is pushed to run, you need a way of knowing the impact of making a change to an API will have everywhere it is being used
- End to end version control and lineage reduce complications as APIs evolve
6. Great API design and documentation are both critical to world class APIs
- But it's only part of the API Product/API Lifecycle and your API/microservice/event/digital transformation strategy.