Skip to content

Latest commit

 

History

History
20 lines (15 loc) · 2.45 KB

producer-design.md

File metadata and controls

20 lines (15 loc) · 2.45 KB

Producer - Design

In the design phase, you invest in the informed design of the surface area of each API, shaping how it works, the protocols and standards it uses, and how each API will conform to wider rules across the organization. Investment in the design of each API, as well as the overall practice of design across operations, fine-tunes your operations and brings operations into alignment.

Elements

  • Patterns - Select which patterns you will use–such as REST, GraphQL, and other common varieties. Patterns will standardize how your APIs work and help designers and developers choose the right tools for the job.

  • Protocols - Make a sensible decision about which protocol to use designing an API, picking the right solution for the project and for the consumers who will be using the product.

  • Standards - Understand the internet, industry, and organizational standards you will use when designing the API, making sure that each API is as consistent as possible.

  • Schema - Establish a schema for all of the objects used as part of requests, responses, publishing, and subscribing when integrating an API into applications.

  • Contracts - Put contracts like OpenAPI and AsyncAPI to work in defining the surface area of each API, providing a machine-readable contract to guide teams’ work.

  • Versioning - Change is inevitable. You need a clear plan for how an API will be versioned, leveraging a common pattern for managing change.

  • Rules - Identify which linting rules you will need to help ensure the API is following central governance and remaining as consistent as possible across teams.

  • Editor - Establish a common, consistent way of directly or visually editing the artifacts used in the API design process, helping clarify the carry load of the design.

  • Examples - Try to provide examples of each part of an API, making actual examples part of each contract that can be used for documentation and mocking.

  • Mocks - Generate a mock representation of an API using its contract, providing an example of what the API will do in production. That will help with the design process and later on, with onboarding.

Design is often discussed in terms of RESTful or web APIs, but this is a universal look at design that can be applied to both synchronous and asynchronous APIs. Design is applied across a variety of API patterns, so you should define a common way to eventually describe and discuss design across all APIs.