apirbcore.md

Azure REST API review board

• Approval by the board is part of the PLR criteria for services
• Looks at adherence to the Microsoft REST API Guidelines + Azure REST API Guidelines
• Follow good practices, avoid anti-patterns across Azure services.
  • Paging
  • Long running operations
  • Error schemas
  • Versioning

Who are on the review board

• Mix of service and client library developers/architects
• Ideally a review has participation from the service "family", azure at large and client library developer.
• Open for all to attend/listen in to meetings

What else is the review board good for

• Service API design help
• Driving consistency across APIs from different services and service families
  • "Horizontal view" of services.
• Gathering common patterns and making them part of the guidelines

Example: new serialization formats, authentication schemes, signing etc.

Cognitive services design guidelines/review board

• Center of excellence for service API design closer to the feature team.
  • Similar to ARM/RPC
• Common concerns among the cognitive family of services.
  • Model versioning
  • Terminology/taxonomy (error codes, language and locale standards etc.)
• Common APIs -> common infrastructure
  • Telemetry
• Buddy system for early engagements
  • Strong correlation between satisfaction with the board and when teams engaged with the board

Service API Versioning

• What are API versions and why do we have them.
• What are breaking changes?
  • Live site/production breaking (incident inducing)
  • Incompatible changes over time (stability of API)

Incident inducing events

• Every change can be breaking
  • Healthy to be appropriately paranoid
• Even no change can be incident inducing
  • Y2k
  • Numbers moving beyond what can be represented in a language
• Use API version to isolate clients from new service behavior

Example - Redirect + new authentication + auth headers provided.

Evolving API changes

• What kind of changes can I make across API versions?
• What kind of changes should I not make across API versions?
  • Can require a massive change in customer's application in order to take advantage of new features.
  • Friction to move to a new API version means that customers won't move unless they absolutely have to.
    • -> You need to support old API versions forever
• Not having breaking changes != not innovating.

Azure SDKs

Azure SDK rchitecture review board

• Approval by the board is part of the PLR criteria for SDK releases
• Looks at adherence to the Azure client library guidelines for our Tier 1 languages.
• Follow good practices, avoid anti-patterns across Azure client libraries.
• Manage approved dependencies (avoid depdendecy conflicts)

Azure client library versioning

• Single package, supports multiple API versions
• Strong correlation of stability over time with good service API evolution.