6 Principals For Good API Design

1. APIs are Forever

Once an API is created, it should never be deleted or changed. “Once you put an API out there, businesses will build on top of it,” Vogels said, adding that changing the API will basically break their businesses.

2. Never Break Backward Compatibility

Backward capability is a must. This is not to say you can’t modify, or improve the API. But whatever changes you make shouldn’t alter the API such that calls from previous versions won’t be affected. As an example, AWS has enhanced its Simple Storage Service (S3) in multiple ways since its launch in 2006, but the first-generation APIs are still supported.

3. Work Backwards from Customer Use Cases

The way to design the APIs is to not start with what the engineers think would make for a good API. Instead, figure out what your users need from the API first, and then “work backward from their use cases. And then come up with a minimal and simplest form of API that you can actually offer,” Vogels said.

As an example, Vogels described an advertisement system that can be used for multiple campaigns. Instead of modifying the API for each new campaign, by embellishing it with multiple flags, maintain a core campaign API call, and then build other, compatible, APIs around it. Keep your API’s as simple as possible, so they can be building blocks for others to use.

4. Create APIs with Explicit and Well-Documented Failure Modes

Speaking of documentation, describing the API’s failure modes — faulty input parameters, and security considerations — need to be included as well. “Because it’s not only about what your API does, it is how it fails,” Vogels said.

5. Create APIs That are Self Describing and Have a Clear, Specific Purpose

Documentation, of course, should always be thorough and up-to-date, but the APIs should also be intuitive at first glance. “You should be able to look at the API, and always be able to figure out what it does,” Vogels said.

6. Avoid Leaking Implementation Details at All Costs

A leaky implementation is one where the underlying implementation details become part of the API itself — a reference to a specific piece of software, for instance. This can be problematic as the customers will grow to rely on these non-essential details, and “you can no longer change that implementation,” Vogels said.

One AWS tool that can help here is Smithy, an open-source program that helps organizations collaborate on API design. It generates API templates that can be easily covered in other formats, such as OpenAPI.

source: https://thenewstack.io/werner-vogels-6-rules-for-good-api-design/