API Implementation

TODO

The Service Client

TODO

Service Methods

TODO

Using azcore.Pipeline

Each supported language has an Azure Core library that contains common mechanisms for cross cutting concerns such as configuration and doing HTTP requests.

DO use the HTTP pipeline component within azcore library for communicating to service REST endpoints.

The HTTP pipeline consists of a HTTP transport that is wrapped by multiple policies. Each policy is a control point during which the pipeline can modify either the request and/or response. We prescribe a default set of policies to standardize how client libraries interact with Azure services. The order in the list is the most sensible order for implementation.

DO implement the following policies in the HTTP pipeline:

  • Telemetry
  • Retry
  • Authentication
  • Response downloader
  • Distributed tracing
  • Logging
  • The HTTP transport itself

☑️ YOU SHOULD use the policy implementations in Azure Core whenever possible. Do not try to “write your own” policy unless it is doing something unique to your service. If you need another option to an existing policy, engage with the [Architecture Board] to add the option.

Using azcore.Policy

TODO

Service Method Parameters

TODO

Parameter validation

TODO

Supporting Types

TODO

Model Types

TODO

Serialization

TODO

Constants as Enumerations

DO define the enumeration’s type to match the type sent/received over-the-wire (string is the most common example).

DO name all values with a prefix of the type’s name.

DO place all values for an enumerated type within their own const block, which is to immediately follow the type’s declaration.

DO define a function named <EnumTypeName>Values() that returns a slice containing all possible values for the enumeration.

DO define a method named ToPtr() on the enumerated type that returns a pointer to the enum value.

// WidgetColor specifies a Widget's color from the list of possible values.
type WidgetColor string

const (
	WidgetColorBlue  WidgetColor = "blue"
	WidgetColorGreen WidgetColor = "green"
	WidgetColorRed   WidgetColor = "red"
)

// WidgetColorValues returns a slice of possible values for WidgetColor.
func WidgetColorValues() []WidgetColor {
	// ...
}

func (c WidgetColor) ToPtr() *WidgetColor {
	return &c
}

SDK Feature Implementation

TODO

Configuration

DO use relevant global configuration settings either by default or when explicitly requested to by the user, for example by passing in a configuration object to a client constructor.

DO allow different clients of the same type to use different configurations.

DO allow consumers of your service clients to opt out of all global configuration settings at once.

DO allow all global configuration settings to be overridden by client-provided options. The names of these options should align with any user-facing global configuration keys.

⛔️ DO NOT change behavior based on configuration changes that occur after the client is constructed. Hierarchies of clients inherit parent client configuration unless explicitly changed or overridden. Exceptions to this requirement are as follows:

  1. Log level, which must take effect immediately across the Azure SDK.
  2. Tracing on/off, which must take effect immediately across the Azure SDK.

Configuration via Environment Variables

DO prefix Azure-specific environment variables with AZURE_.

✔️ YOU MAY use client library-specific environment variables for portal-configured settings which are provided as parameters to your client library. This generally includes credentials and connection details. For example, Service Bus could support the following environment variables:

  • AZURE_SERVICEBUS_CONNECTION_STRING
  • AZURE_SERVICEBUS_NAMESPACE
  • AZURE_SERVICEBUS_ISSUER
  • AZURE_SERVICEBUS_ACCESS_KEY

Storage could support:

  • AZURE_STORAGE_ACCOUNT
  • AZURE_STORAGE_ACCESS_KEY
  • AZURE_STORAGE_DNS_SUFFIX
  • AZURE_STORAGE_CONNECTION_STRING

DO get approval from the [Architecture Board] for every new environment variable.

DO use this syntax for environment variables specific to a particular Azure service:

  • AZURE_<ServiceName>_<ConfigurationKey>

Where ServiceName is the canonical shortname without spaces, and ConfigurationKey refers to an unnested configuration key for that client library.

⛔️ DO NOT use non-alpha-numeric characters in your environment variable names with the exception of underscore. This ensures broad interoperability.

Logging

Client libraries must support robust logging mechanisms so that the consumer can adequately diagnose issues with the method calls and quickly determine whether the issue is in the consumer code, client library code, or service.

DO use the Logger API provided within azcore as the sole logging API throughout all client libraries.

DO define constant classification strings using the azcore.LogClassification type, then log using these values.

DO log HTTP request line, response line, and all header/query parameter names.

⛔️ DO NOT log payloads or HTTP header/query parameter values that aren’t on the allow list. For header/query parameters not on the allow list use the value <REDACTED> in place of the real value.

Distributed Tracing

DO abstract the underlying tracing facility, allowing consumers to use the tracing implementation of their choice.

DO create a new trace span for each API call. New spans must be children of the context that was passed in.

DO use <package name>.<type name>.<method name> as the name of the span.

DO propagate tracing context on each outgoing service request through the appropriate headers to support a tracing service like Azure Monitor or ZipKin. This is generally done with the HTTP pipeline.

Telemetry

TODO

Testing

TODO