Skip to content

Instantly share code, notes, and snippets.

@mikekistler

mikekistler/design-principles.md

Created July 12, 2022 03:43
Show Gist options
  • Save mikekistler/186cf9e75370a35b64248190aaed193f to your computer and use it in GitHub Desktop.
Save mikekistler/186cf9e75370a35b64248190aaed193f to your computer and use it in GitHub Desktop.
Download ZIP
Azure REST API Design Principles
Raw
design-principles.md

The thought occurred to me today to recast the Azure SDK Design Principles into a corresponding set of design principles for Azure REST APIs. This only took about 5 minutes and I think could be a nice complement to our REST API Guidelines. What do you think?

Azure REST API Design Principles

Azure REST APIs should be designed to enhance the productivity of developers connecting to Azure services. Other qualities (such as completeness, extensibility, and performance) are important but secondary. Productivity is achieved by adhering to the principles described below:

Idiomatic

  • The REST API should follow the general design guidelines and conventions for HTTP REST APIs. It should feel natural to a developer familiar with REST.
  • We embrace the ecosystem with its strengths and its flaws.
  • We work with the ecosystem to improve it for all developers.

Consistent

  • Azure REST APIs should be consistent within the service, consistent across services and consistent with the client libraries that sit on top of the REST API. In cases of conflict, consistency with REST API design is the highest priority and consistency between with client libraries is the lowest priority.
  • Service-agnostic concepts such as logging, HTTP communication, and error handling should be consistent. The developer should not have to relearn service-agnostic concepts as they move between services.
  • Consistency of terminology between the REST API and the service is a good thing that aids in diagnosability.
  • All differences between the service and REST API must have a good (articulated) reason for existing, rooted in idiomatic usage rather than whim.
  • The Azure REST API feels like a single product developed by a single team.
  • There should be feature parity between the REST API and client libraries.

Approachable

  • We are experts in the supported technologies so our customers, the developers, don’t have to be.
  • Developers should find great documentation (hero tutorial, how to articles, samples, and API documentation) that makes it easy to be successful with the Azure service.
  • Getting off the ground should be easy through the use of predictable defaults that implement best practices. Think about progressive concept disclosure.
  • The REST API definition should be easily acquired for developers that want it.
  • Developers can be overwhelmed when learning new service concepts. The core use cases should be discoverable.

Diagnosable

  • The developer should be able to understand what is going on.
  • It should be discoverable when and under what circumstances a network call is made.
  • Defaults are discoverable and their intent is clear.
  • Logging, tracing, and exception handling are fundamental and should be thoughtful.
  • Error messages should be concise, correlated with the service, actionable, and human readable. Ideally, the error message should lead the consumer to a useful action that they can take.
  • It should be easy for developers to test individual operations with common REST API tooling (e.g. Postman)

Dependable

  • Breaking changes are more harmful to a user’s experience than most new features and improvements are beneficial.
  • Incompatibilities should never be introduced deliberately without thorough review and very strong justification.
  • Do not rely on dependencies that can force our hand on compatibility.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment