Throughout the guidelines, the following terms should be understood:
- Architecture Board
- The Azure Developer Experience Architecture Board is comprised of language experts who advise and review client libraries used for accessing Azure services.
- Azure SDK
- The collection of client libraries for a single target language, used for accessing Azure services.
- Azure Core
- A dependency of many client libraries. The Azure Core library provides access to the HTTP pipeline, common credential types, and other types that are appropriate to the Azure SDK as a whole.
- A class that provides methods to send requests to the service.
- Client Library
- A library (and associated tools, documentation, and samples) that consumers use to ease working with an Azure service. There is generally a client library per Azure service and per target language. Sometimes a single client library will contain the ability to connect to multiple services.
- Where appropriate to disambiguate between the various types of developers, we use the term consumer to indicate the developer who is using a client library in an app to connect to an Azure service.
- The comments embedded within the code that describe the API surface being implemented. The docstrings are extracted and post-processed during the build to generate API reference documentation.
- Library Developer
- Where appropriate to disambiguate between the various types of developers, we use the term library developer to indicate the developer who is writing a client library.
- A client library after it has been packaged for distribution to consumers. Packages are generally installed using a package manager from a package repository.
- Package Repository
pipto install packages into their project.
- Progressive Concept Disclosure
- The first interaction with the client library should not rely on advanced service concepts. As the consumer of the library becomes more adept, we expose the concepts necessary at the point at which the consumer needs those concepts for implementation. Progressive Disclosure was first discussed by the Nielson Norman Group as an approach to designing better user interfaces.
- Service client
- The starting points for consumers calling Azure services with the Azure SDK. A service client is distinguished from other clients in that it can be directly constructed. Each client library should have at least one service client in its main namespace, so it’s easy to discover.
Each requirement in this document is labelled and color-coded to show the relative importance. In order from highest importance to lowest importance:
✔️ YOU MAY consider this advice if appropriate to your situation. No notification to the architecture board is required.