4 Essential Tips to Building a Unified API Design

As APIs are adopted in more and more organizations, the need for successful API design and implementation becomes more pressing. Companies that adopt a single API definition format (OpenAPI, AsyncAPI, Schema Definition Language, Protobuff, etc.) are likely to find their options limited as their API ecosystem grows and matures over time.

In order to avoid forcing the entire company to adopt a single API style or format, no matter the requirements of providers and consumers, we need a unified API design process. One that doesn’t pre-determine implementation details such as REST, GraphQL, gRPC, and others.

We asked the ultimate API expert Mike Amundsen to help us work around these issues.

Mike came back to us with a method for unifying API design.

Based on materials in Design and Build Great Web APIs, Mike’s talk describes a simple, repeatable process for API designers to capture and document design details in a way that allows API developers to make their own decisions on which API style best fits the needs of the company and the consumer.

Here are a few of the main takeaways:

• Break the HTTP-centric grip on your API design process: Stop using URLs, methods, resources and status codes as design elements (Note: you still need them as implementation details)
    
• Embrace interface descriptions: Stick to using properties and actions to describe your API designs
    
• Enable translations: From description language to translation language — translate your unified design documents into implementation-specific definitions
    
• Future proof your design process: Even if you only use one API style today, prepare for supporting others in the future