Android Azure SDK Design Guidelines

Introduction

The following document describes Android specific guidelines for designing Azure SDK client libraries. These guidelines also expand on and simplify language-independent General Azure SDK Guidelines. More specific guidelines take precedence over more general guidelines.

The Android guidelines are for the benefit of client library designers targeting service applications written for the native Android ecosystem. You do not have to write a client library for Android if your service is not normally accessed from mobile apps.

Design principles

The main value of the Azure SDK is productivity. Other qualities, such as completeness, extensibility, and performance are important but secondary. We ensure our customers can be highly productive when using our libraries by ensuring these libraries are:

Idiomatic

• The SDK should follow the general design guidelines and conventions for Android libraries written in Java. It should feel natural to an Android developer.
• We embrace the ecosystem with its strengths and its flaws.
• We work with the ecosystem to improve it for all developers.

We are not trying to fix bad parts of the language ecosystem; we embrace the ecosystem with its strengths and its flaws.

Consistent

• The Azure SDK feels like a single product of a single team, not simply a collection of libraries for Azure services.
• Users learn common concepts once; apply the knowledge across all SDK components.
• All differences from the guidelines must have good reasons.

Approachable

• Small number of steps to get started; power knobs for advanced users.
• Small number of concepts; small number of types; small number of members.
• Approachable by our users, not by engineers designing the SDK components.
• Easy to find great getting started guides and samples.
• Easy to acquire.

Dependable

• 100% backward compatible.
• Great logging and error messages.
• Predictable support lifecycle, feature coverage, and quality.

General Guidelines

✅ DO follow the General Azure SDK Guidelines.

✅ DO locate all source code in the azure/azure-sdk-for-android GitHub repository.

✅ DO write the client libraries using Java 8.

The intent is to ensure that the client library is idiomatic for Android applications while remaining compatible with a minimum API level of Android 15 (Ice Cream Sandwich).

Support for non-HTTP Protocols

Currently, this document describes guidelines for client libraries exposing HTTP services. If your service is not HTTP-based, please contact the Azure SDK Architecture Board for guidance.

Azure SDK API Design

Azure services are exposed to Android developers as one or more service client types and a set of supporting types.

Service Client

Service clients are the main starting points for developers calling Azure services with the Azure SDK. Each client library should have at least one client in its main namespace, so it’s easy to discover. The guidelines in this section describe patterns for the design of a service client. Because for Android both synchronous and asynchronous service clients are required, the sections below are organized into general service client guidance, followed by sync- and async-specific guidance.

✅ DO name service client types with the Client suffix (for example, ConfigurationClient).

✅ DO annotate all service clients with the @ServiceClient annotation.

✅ DO place service client types that the consumer is most likely to interact with in the root package of the client library (for example, com.azure.android.<group>.servicebus). Specialized service clients should be placed in sub-packages.

✅ DO ensure that all service client classes are immutable and stateless upon instantiation.

✅ DO have separate service clients for sync and async APIs.

☑️ YOU SHOULD support only those features provided by the Azure service that would make sense to access from a mobile app. Mobile apps are inherently end-user facing applications, and only a subset of Azure services and features are intended for use by these type of applications. While completeness is valuable and gaps in functionality can cause frustration, a smaller binary size and an opinionated stance of only providing end user facing functionality will make our libraries easier and more desirable for app developers to use.

✅ DO provide a public API whose shape matches the public API shape provided in the equivalent iOS library as closely as possible. Clients should have the same names and provide the same functionality in their public APIs, and while method naming should be idiomatic to each platform, consistency in naming between the two platforms is the next most important consideration.

Sync Service Clients

✅ DO offer a sync service client named <ServiceName>Client containing all non-streaming service methods. More than one service client may be offered for a single service. An example of a sync client is shown below:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.<group>.<service_name>;

@ServiceClient(
    builder = <service_name>ClientBuilder.class,
    serviceInterfaces = <service_name>Service.class)
public final class <service_name>Client {
    // Package-private constructors only - all instantiation is done with builders.
    <service_name>Client(<parameters>) {
        // ...
    }

    // Service methods...

    // A single response API.
    public <model> <service_operation>(<parameters>) {
        // ...
    }

    // A single response API including HTTP response details.
    public Response<<model>> <service_operation>(<parameters>) {
        // ...
    }
    
    // A paginated sync list API including HTTP response details (refer to pagination section for more details).
    public PagedIterable<<model>> list<service_operation>(<parameters>) {
        // ...
    }

    // Other members.
    ...
}

Refer to the ChatClient class for a fully built-out example of how a sync client should be constructed.

Async Service Clients

✅ DO offer an async service client named <ServiceName>AsyncClient containing all service methods. More than one service client may be offered for a single service. An example of an async client is shown below:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.<group>.<service_name>;

@ServiceClient(
    builder = <service_name>ClientBuilder.class,
    serviceInterfaces = <service_name>Service.class,
    isAsync = true)
public final class <service_name>AsyncClient {
    // Package-private constructors only - all instantiation is done with builders.
    <service_name>AsyncClient(<parameters>) {
        // ...
    }

    // Service methods...

    // A single response API.
    public CompletableFuture<<model>> <service_operation>(<parameters>) {
        // ...
    }

    // A single response API including HTTP response details.
    public CompletableFuture<Response<<model>>> <service_operation>(<parameters>) {
        // ...
    }

    // A paginated async list API including HTTP response details (refer to pagination section for more details).
    public CompletableFuture<PagedAsyncCollection<<model>>> list<service_operation>(<parameters>) {
        // ...
    }

    // Other members.
    ...
}

Refer to the ChatAsyncClient class for a fully built-out example of how a sync client should be constructed.

✅ DO use Android retro future’s CompletableFuture to provide consumers with a high-quality async API.

⛔️ DO NOT write custom APIs for streaming or async operations. Make use of the existing functionality offered in the Azure core library. Discuss proposed changes to the Azure core library with the Architecture Board. Refer to the Azure Core Types section for more information.

Service Client Creation

⛔️ DO NOT provide any public or protected constructors in the service client. Keep visibility to a minimum by using package-private constructors that may only be called by types in the same package, and then enable instantiation of the service client through the use of service client builders, detailed below.

✅ DO offer a fluent builder API for constructing service clients named <service_name>ClientBuilder, which must support building a sync service client instance and an async service client instance (where appropriate). It must offer buildClient() and buildAsyncClient() API to create a synchronous and asynchronous service client instance, respectively. Shown in the first code sample below is a generalized template, and following that is a stripped-down example builder.

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.<group>.<service_name>;

// Template of how a builder should look.
@ServiceClientBuilder(serviceClients = {<service_name>Client.class, <service_name>AsyncClient.class})
public final class <service_name>ClientBuilder {
    // private fields for all settable parameters
    ...

    // This is the public constructor used to create the service client, so a public access modifier makes sense here.
    // This is required, and it is intended to prevent any public constructors in the service client itself, because we
    // do not want to allow users to create a service client directly.
    public <service_name>ClientBuilder() {
        // Any initialization necessary for the builder.
    }

    // The buildClient() method returns a new instance of the sync client each time it is called.
    public <service_name>Client buildClient() {
        // Create an async client and pass that into the sync client for sync-over-async impl.
        return new <service_name>Client(buildAsync());
    }

    // The buildAsyncClient() method returns a new instance of the async client each time it is called.
    public <service_name>Client buildAsyncClient() {
        // Configuration of pipeline, etc.
        ...

        // Instantiate new async client instance.
        return new <service_name>AsyncClient(serviceEndpoint, pipeline);
    }

    // Fluent API, each returning 'this', and one for each parameter to configure.
    public <service_name>ClientBuilder <property>(<parameter>) {
        builder.<property>(<parameter>);
        return this;
    }
}

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.data.appconfiguration;

// Concrete example of a builder.
@ServiceClientBuilder(serviceClients = {ConfigurationAsyncClient.class, ConfigurationClient.class})
public final class ConfigurationClientBuilder {
    private String endpoint;
    private TokenCredential tokenCredential;
    private ConfigurationServiceVersion version = ConfigurationServiceVersion.getLatest();
    // Other fields and its setters are omitted for brevity.

    // Public constructor - this is the only available front door to creating a service client instance.
    public ConfigurationClientBuilder() {
        // Empty constructor
    }

    // The buildClient() method returns a new instance of the sync client each time it is called.
    public ConfigurationClient buildClient() {
        // Create an async client and pass that into the sync client for sync-over-async impl.
        return new ConfigurationClient(buildAsyncClient());
    }

    // The buildAsyncClient() method returns a new instance of the async client each time it is called.
    public ConfigurationAsyncClient buildAsyncClient() {
        // Configuration of pipeline, etc.
        HttpPipeline pipeline = buildOrGetHttpPipeline();

        // Instantiate new async client instance.
        return new ConfigurationAsyncClient(endpoint, pipeline, serviceVersion);
    }

    // Fluent APIs, each returning 'this', and one for each parameter to configure.

    public ConfigurationClientBuilder endpoint(String endpoint) {
        try {
            new URL(endpoint);
        } catch (MalformedURLException ex) {
            throw logger.logExceptionAsWarning(new IllegalArgumentException("'endpoint' must be a valid URL."));
        }
        this.endpoint = endpoint;
        return this;
    }
}

✅ DO offer build method ‘overloads’ for when a builder can build multiple client types. These methods must be named in the form build<client>Client() and build<client>AsyncClient(). For example, buildBlobClient() and buildBlobAsyncClient().

✅ DO annotate service client builders with the @ServiceClientBuilder annotation, setting the annotation parameters appropriately for the service client (e.g. async is true for async service clients).

✅ DO ensure consistency across all HTTP-based client libraries, by using the following names for client builder fluent API:

endpoint may be renamed if a more user-friendly name can be justified. For example, a blob storage library developer may consider using new BlobClientBuilder.blobUrl(..). In this case, the endpoint API should be removed.

✅ DO allow the consumer to construct a service client with the minimal information needed to connect and authenticate to the service.

✅ DO ensure the builder will instantiate a service client into a valid state. Throw an IllegalStateException when the user calls the build*() methods with a configuration that is incomplete or invalid.

Service Versions

✅ DO call the highest supported service API version by default, and ensure this is clearly documented.

⛔️ DO NOT include preview API versions in a stable SDK release’s API version enum.

✅ DO expose preview API versions only in beta SDKs.

✅ DO provide an enum of supported service API versions that can be supplied via the options class when initializing the service client, as shown below:

public enum ConfigurationServiceVersion implements ServiceVersion {
  V1_0("1.0");

  private final String version;

  ConfigurationServiceVersion(String version) {
    this.version = version;
  }

  @Override
  public String getVersion() {
    return this.version;
  }

  /**
   * Gets the latest service API version supported by this client library.
   *
   * @return The latest {@link ConfigurationServiceVersion}.
   */
  public static ConfigurationServiceVersion getLatest() {
    return V1_0;
  }
}

This can then be called by the developer as such:

ConfigurationClient client = new ConfigurationClientBuilder()
    .credential(<tokenCredential>)
    .endpoint("<endpoint>")
    .serviceVersion(ConfigurationServiceVersion.V1_0) // Set the version to V1.
    .buildClient();

// calls V1 service API
ConfigurationSetting setting = client.getConfigurationSetting("name", "label");

✅ DO include a getLatest() method on the client’s API version enum which returns the latest preview API version for beta SDKs and the latest GA API version for stable SDKs.

Service Methods

Service methods are the methods on the client that invoke operations on the service.

✅ DO use standard JavaBean naming prefixes for all methods that are not service methods.

⛔️ DO NOT use the suffix Async in methods that do operations asynchronously. Let the fact the user has an instance of an ‘async client’ provide this context.

⛔️ DO NOT provide multiple asynchronous methods for a single REST endpoint in the same library, unless to provide overloaded methods to enable alternative or optional method parameters.

One of the Azure Core types is com.azure.core.android.util.Context, which acts as an append-only key-value map, and which by default is empty. The Context allows end users of the API to modify the outgoing requests to Azure on a per-method call basis, for example to enable distributed tracing.

✅ DO provide an overload method that takes a com.azure.android.core.util.Context argument for each service operation in sync clients only. The Context argument must be the last argument into the service method (except where varargs are used). If a service method has multiple overloads, only the ‘maximal’ overloads need to have the Context argument. A maximal overload is one that has a full set of arguments. It may not be necessary to offer a ‘Context overload’ in all cases. We prefer a minimal API surface, but Context must always be supported.

getFoo()
getFoo(x)
getFoo(x, y)
getFoo(x, y, z) // maximal overload
getFoo(a)       // maximal overload

// this will result in the following two methods being required 
// (replacing the two maximal overloads above)
getFoo(x, y, z, Context)
getFoo(a, Context)

⛔️ DO NOT include overloads that take Context in async clients. Async clients use the [subscriber context built into Reactor Flux and Mono APIs][reactor-context].

Naming

✅ DO name service methods using a standardized set of verbs or verb prefixes within a set of client libraries for a service. Prefer the use of the following terms for CRUD operations:

☑️ YOU SHOULD remain flexible and use names best suited for developer experience. Don’t let the naming rules result in non-idiomatic naming patterns. For example, Java developers prefer list operations over getAll operations.

✅ DO use the verb as as prefix for the method name when object(s) the action will apply to or return is unclear. For example, prefer storageBlobClient.listContainers() rather than storageBlobClient.list().

✅ DO prefix methods in sync clients that create or vend subclients with get and suffix with Client. For example, container.getBlobClient().

✅ DO prefix methods in async clients that create or vend subclients with get and suffix with AsyncClient. For example, container.getBlobAsyncClient().

Cancellation

✅ DO support an optional CancellationToken object. This object allows the developer to call cancel() on the token or set a timeout, after which a best-effort attempt is made to cancel the request.

✅ DO cancel any in-flight requests when a developer calls cancel() on the CancellationToken. If the body of the client method includes multiple, sequential operations, you must check for cancellation before executing any operations after the first. Since the underlying Android network APIs do not permit cancellation of in-flight requests, you must also check for cancellation immediately after receiving any response. If cancellation has been requested, indicate that the call has been cancelled and do not return or otherwise further process the response.

✅ DO return an AzureException when cancellation is requested stating that the request was canceled, even if the request was successful.

Return Types

Requests to the service fall into two basic groups: methods that make a single logical request, and methods that make a deterministic sequence of requests. An example of a single logical request is a request that may be retried inside the operation. An example of a deterministic sequence of requests is a paged operation.

The logical entity is a protocol neutral representation of a response. The logical entity may combine data from headers, body, and the status line. For example, you may expose an ETag header as a property on the logical entity. Response<T> is the ‘complete response’. It contains HTTP headers, status code, and the T object (a deserialized object created from the response body). The T object would be the ‘logical entity’.

✅ DO return the logical entity (i.e. the T) for all synchronous service methods.

✅ DO return the logical entity (i.e. the T) wrapped inside an android-retrofuture’s CompletableFuture for all non-streaming asynchronous service methods that make network requests. Do not use the JDK’s java.util.concurrent.CompletableFuture, as this type is not available on all Android devices.

Return Response<T> on the maximal overload for a service method with WithResponse appended to the name. For example:

Foo foo = client.getFoo(a);
Foo foo = client.getFoo(a, b);
Foo foo = client.getFoo(a, b, c, context); // This is the maximal overload, so it is replaced with the 'withResponse' 'overload' below
Response<Foo> response = client.getFooWithResponse(a, b, c, context);

✅ DO make it possible for a developer to access the complete response, including the status line, headers, and body. The type Response<T> encodes this requirement and is the recommended return type for async client methods. The T parameter is the type of the logical entity.

✅ DO provide examples on how to access the raw and streamed response for a request, where exposed by the client library. We don’t expect all methods to expose a streamed response.

✅ DO return an instance of the PagedIterable or PagedAsyncCollection classes for all paged operations. For more information on what to return for list operations, refer to Pagination.

For methods that combine multiple requests into a single call:

⛔️ DO NOT return headers and other per-request metadata unless it’s obvious as to which specific HTTP request the methods return value corresponds to.

✅ DO provide enough information in failure cases for a developer to take appropriate corrective action, including a message describing what went wrong and details on the corrective actions to take.

Service Method Parameters

✅ DO accept all arguments required to execute a method call as individual parameters to the method. An argument is considered required if it is flagged as such in the service’s API spec or if the library author deems it to be essential to the developer experience of the client API.

Option Parameters

Service methods fall into two main groups when it comes to the number and complexity of parameters they accept:

• Service Methods with simple inputs, simple methods for short
• Service Methods with complex inputs, complex methods for short

Simple methods are methods that take up to six parameters, with most of the parameters being simple primitive types. Complex methods are methods that take a larger number of parameters and typically correspond to REST APIs with complex request payloads.

Simple methods should follow standard Java best practices for parameter list and overload design.

Complex methods should introduce an option parameter to represent the request payload. Consideration can subsequently be made for providing simpler convenience overloads for the most common scenarios. This is referred to in this document as the ‘options pattern’, and is demonstrated in the code below:

public class BlobContainerClient {
    // Simple service methods.
    public BlobInfo uploadBlob(String blobName, byte[] content);
    public Response<BlobInfo> uploadBlobWithResponse(String blobName, byte[] content, Context context);

    // Complex service methods, note the introduction of the 'CreateBlobOptions' type.
    public BlobInfo createBlob(CreateBlobOptions options);
    public Response<BlobInfo> createBlobWithResponse(CreateBlobOptions options, Context context);

    // Convenience overload[s].
    public BlobInfo createBlob(String blobName);
}

@Fluent
public class CreateBlobOptions {
    private String blobName;
    private PublicAccessType access;
    private Map<String, String> metadata;

    // Constructor enforces the requirement that blobName is always set.
    public CreateBlobOptions(String blobName) {
        this.blobName = blobName;
    }

    public String getBlobName() {
        return blobName;
    }

    public CreateBlobOptions setAccess(PublicAccessType access) {
        this.access = access;
        return this;
    }

    public PublicAccessType getAccess() {
        return access;
    }

    public CreateBlobOptions setMetadata(Map<String, String> metadata) {
        this.metadata = metadata;
        return this;
    }

    public Map<String, String> getMetadata() {
        return metadata;
    }
}

✅ DO name the options type after the name of the service method it is used for, such that the type is named <operation>Options. For example, above the method was createBlob, and so the options type was named CreateBlobOptions.

✅ DO use the options parameter pattern for complex service methods.

✔️ YOU MAY use the options parameter pattern for simple service methods that you expect to grow in the future.

✔️ YOU MAY add simple overloads of methods using the options parameter pattern.

If in common scenarios, users are likely to pass just a small subset of what the options parameter represents, consider adding an overload with a parameter list representing just this subset.

⛔️ DO NOT introduce method overloads that take a subset of the parameters as well as the options parameter, except for parameters that are for client-side use only (e.g. Context).

✅ DO use rich types where possible for options. For example, use the Date type for dates. When not possible, name the option with a suffix to express the expected type. If the expected type is a unit, the suffix should follow the format In<Unit>. Unit should be ms for milliseconds, and otherwise the name of the unit. Examples include timeoutInMs and delayInSeconds.

✅ DO use the options parameter type, if it exists, for all *WithResponse methods. If no options parameter type exists, do not create one solely for the *WithResponse method.

✅ DO store options classes (and supporting enumerations / classes referenced by such models) in a root-level options package, to make options types distinct from service clients and model types.

✅ DO design options types with the same design guidance as given below for model class types, namely fluent setters for optional arguments, using the standard JavaBean naming convention of get*, set*, and is*. Additionally, there may be constructor overloads for each combination of required arguments.

✔️ YOU MAY introduce constructor overloads for each combination of required arguments (in a similar manner to required properties on model types).

Parameter Validation

The service client will have several methods that perform requests on the service. Service parameters are directly passed across the wire to an Azure service. Client parameters are not passed directly to the service, but used within the client library to fulfill the request. Examples of client parameters include values that are used to construct a URI, or a file that needs to be uploaded to storage.

✅ DO validate client parameters.

⛔️ DO NOT validate service parameters. This includes null checks, empty strings, and other common validating conditions. Let the service validate any request parameters.

Common parameter validations include null checks, empty string checks, and range checks. Let the service validate its parameters.

✅ DO test the developer experience when invalid service parameters are passed in. Ensure clear error messages are generated by the client. If the developer experience is inadequate, work with the service team to correct the problem.

Methods Returning Collections (Paging)

Many Azure REST APIs return collections of data in batches or pages. A client library will expose such APIs as special enumerable types PagedIterable<T> or PagedAsyncCollection<T>, for synchronous and asynchronous APIs, respectively. These types are located in the Azure Core library.

✅ DO return PagedIterable<T> from service methods in synchronous that return a collection of items. For example, the configuration service sync client should offer the following API:

public final class ConfigurationClient {
    // Synchronous API returning a PagedIterable of ConfigurationSetting instances.
    public PagedIterable<ConfigurationSetting> listSettings(...) {
        ...
    }
}

PagedIterable allows developers to write code that works using the standard for loop syntax (as it is an Iterable), and also to work with a Java Stream (as there is a stream() method). Consumers may also call streamByPage() and byPage() methods to work on page boundaries. Subclasses of these types are acceptable as return types too, so long as the naming convention generally follows the pattern <serviceName>PagedIterable or <operation>PagedAsyncCollection.

⛔️ DO NOT return other collection types for sync APIs that return collections (for example, do not return List, Stream, Iterable, or Iterator).

✅ DO return PagedAsyncCollection<T> (or an appropriately-named subclass) for asynchronous APIs that expose a collection of items. Even if the service does not support pagination, always return PagedAsyncCollection<T>, as it allows for consumers to retrieve response information in a consistent manner.

public final class ConfigurationAsyncClient {
    // Asynchronous API returning a PagedAsyncCollection of ConfigurationSetting instances
    public PagedAsyncCollection<ConfigurationSetting> listSettings(SettingSelector options, Context context) {
        // The lambda is a Function<PagedResponse<String, CompletableFuture<PagedResponse<T>>> returning the pages of
        // results as a CompletableFuture<PagedResponse<T>>.
        return new PagedAsyncCollection<>(pageId -> listSettingsByPageId(pageId));
    }
}

Consumers of this API can consume individual items by treating the response as a CompletableFuture<T>:

client.listSettings(..)
      .forEach(item -> System.out.println("Processing item " + item));

The consumer may process items page-by-page instead:

client.listSettings(..)
      .forEachPage(page -> {
        // Page is a PagedResponse, which implements Page and Response, so there exists:
        //  * List<T> of items,
        //  * continuationToken (represented as a String),
        //  * Status code,
        //  * HTTP headers,
        //  * HTTP request
        System.out.println("Processing page " + page)
});

The PagedAsyncCollection.forEachPage() offers an overload to accept a continuationToken string, which will begin the returned CompletableFuture at the page specified by this token.

✔️ YOU MAY subclass the Azure Core paged and iterable APIs, where appropriate, to offer additional, service specific API to users. If this is done, the subtype must be named as it currently is, prefixed with the name of the service. For example, SearchPagedAsyncCollection and SearchPagedIterable. Subtypes are expected to be placed within a util package existing within the root package.

✅ DO use the same type for entities returned from a list operation vs. a get operation if those operations return different views of the same result. For example a list operation may provide only a minimal representation of each result, with the expectation that a get operation must be performed for each result to access the full representation. If the representations are compatible, reuse the same type for both the list and the get operation. Otherwise, it is permissible to use distinct types for each operation.

⛔️ DO NOT expose an iterator over each individual item if getting each item requires a corresponding GET request to the service. One GET per item is often too expensive and so not an action we want to take on behalf of users.

Methods Invoking Long Running Operations

Long-running operations are uncommon in a mobile context. If you feel like you need long running operations, contact the Azure SDK mobile team for advice.

TODO: Expand upon why LROs are uncommon in a mobile context.

Conditional Request Methods

Conditional requests are normally performed using HTTP headers. The primary usage provides headers that match the ETag to some known value. The ETag is an opaque identifier that represents a single version of a resource. For example, adding the following header will translate to “if the record’s version, specified by the ETag, is not the same”.

If-Not-Match: "etag-value"

With headers, tests are possible for the following:

• Unconditionally (no additional headers)
• If (not) modified since a version (If-Match and If-Not-Match)
• If (not) modified since a date (If-Modified-Since and If-Unmodified-Since)
• If (not) present (If-Match and If-Not-Match with a ETag=* value)

Not all services support all of these semantics, and may not support any of them. Developers have varying levels of understanding of the ETag and conditional requests, so it is best to abstract this concept from the API surface. There are two types of conditional requests we need to be concerned with:

Safe conditional requests (e.g. GET)

These are typically used to save bandwidth in an “update cache” scenario, i.e. I have a cached value, only send me the data if what the service has is newer than my copy. These return either a 200 or a 304 status code, indicating the value was not modified, which tells the caller that their cached value is up to date.

Unsafe conditional requests (e.g. POST, PUT, or DELETE)

These are typically used to prevent losing updates in an optimistic concurrency scenario, i.e. I’ve modified the cached value I’m holding, but don’t update the service version unless it has the same copy I’ve got. These return either a success or a 412 error status code, indicating the value was modified, to indicate to the caller that they’ll need to retry their update if they want it to succeed.

These two cases are handled differently in client libraries. However, the form of the call is the same in both cases. The signature of the method should be:

client.<method>(<item>, requestOptions)

The requestOptions field provides preconditions to the HTTP request. The Etag value will be retrieved from the item that is passed into the method where possible, and method arguments where not possible. The form of the method will be modified based on idiomatic usage patterns in the language of choice. In cases where the ETag value is not known, the operation cannot be conditional. If the library developer does not need to support advanced usage of precondition headers, they can add a boolean parameter that is set to true to establish the condition. For example, use one of the following boolean names instead of the conditions operator:

• onlyIfChanged
• onlyIfUnchanged
• onlyIfMissing
• onlyIfPresent

In all cases, the conditional expression is “opt-in”, and the default is to perform the operation unconditionally.

The return value from a conditional operation must be carefully considered. For safe operators (e.g. GET), return a response that will throw if the value is accessed (or follow the same convention used fro a 204 No Content response), since there is no value in the body to reference. For unsafe operators (e.g. PUT, DELETE, or POST), throw a specific error when a Precondition Failed or Conflict result is received. This allows the consumer to do something different in the case of conflicting results.

☑️ YOU SHOULD accept a conditions parameter (which takes an enumerated type) on service methods that allow a conditional check on the service.

☑️ YOU SHOULD accept an additional boolean or enum parameter on service methods as necessary to enable conditional checks using ETag.

☑️ YOU SHOULD include the ETag field as part of the object model when conditional operations are supported.

⚠️ YOU SHOULD NOT throw an error when a 304 Not Modified response is received from the service, unless such errors are idiomatic to the language.

☑️ YOU SHOULD throw a distinct error when a 412 Precondition Failed response or a 409 Conflict response is received from the service due to a conditional check.

Hierarchical Clients

TODO: Add discussion of hierarchical clients

Supporting Types

Model Types

Model types are classes that developers of applications use to provide required information into, or to receive information from, Azure services. For example:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.ai.textanalytics.models;

@Fluent
public final class PiiTaskParameters {
    // Optional properties.
    private PiiTaskParametersDomain domain;
    private String modelVersion = "latest";

   // Optional properties have getters and fluent setters.
    public PiiTaskParametersDomain getDomain() {
        return this.domain;
    }

    public PiiTaskParameters setDomain(PiiTaskParametersDomain domain) {
        this.domain = domain;
        return this;
    }
   
    public String getModelVersion() {
        return this.modelVersion;
    }

    public PiiTaskParameters setModelVersion(String modelVersion) {
        this.modelVersion = modelVersion;
        return this;
    }
}

⛔️ DO NOT offer a separate builder class for model classes.

✅ DO provide public constructors for all model classes that a user is allowed to instantiate. Model classes that are not instantiable by the user, for example if they are model types returned from the service, must not have any publicly visible constructors.

Because model types can represent many different kinds of models, it is important that they can correctly enforce required properties. Whilst many models have no required properties, some do, and moreso, some models can even support multiple mutually exclusive sets of required properties.

✅ DO provide a no-args constructor if a model type has no required properties.

✅ DO provide one or more constructors with arguments, if a model type has required properties. If there are multiple mutually exclusive sets of supported required parameters, a constructor must be introduced for each of these. For example:

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
package com.azure.android.ai.textanalytics.models;

@Fluent
public final class TextDocumentInput {
    // Required properties.
    private final String id;
    private final String text;
  
    // Optional property.
    private String language;
  
    // Constructor to enforce setting the required properties.
    public TextDocumentInput(String id, String text) {
        this.id = Objects.requireNonNull(id, "'id' cannot be null.");
        this.text = Objects.requireNonNull(text, "'text' cannot be null.");
    }
  
    // Required properties only have getters.
    public String getId() {
        return this.id;
    }
  
    public String getText() {
        return this.text;
    }
  
    // Optional property has both getter and fluent setter.
    public String getLanguage() {
        return this.language;
    }
  
    public TextDocumentInput setLanguage(String language) {
        this.language = language;
        return this;
    }
}

✅ DO provide a fluent setter API to configure the model class, where each set method should return this. This allows chaining of set operations.

✅ DO override all set methods when extending a fluent type to return the extended type. This allows chaining of set operations on the sub-class.

@Fluent
public class SettlementOptions {
    private ServiceBusTransactionContext transactionContext;

    public ServiceBusTransactionContext getTransactionContext() {
        return transactionContext;
    }

    public SettlementOptions setTransactionContext(ServiceBusTransactionContext transactionContext) {
        this.transactionContext = transactionContext;
        return this;
    }
}

@Fluent
public final AbandonOptions extends SettlementOptions {
    private Map<String, Object> propertiesToModify;

    public Map<String, Object> getPropertiesToModify() {
        return propertiesToModify;
    }

    public AbandonOptions setPropertiesToModify(Map<String, Object> propertiesToModify) {
        this.propertiesToModify = propertiesToModify;
        return this;
    }

    // Override setter method of the parent class
    @Override
    public AbandonOptions setTransactionContext(ServiceBusTransactionContext transactionContext) {
        super.setTransactionContext(transactionContext);
        return this;
    }
}

✅ DO apply the @Fluent annotation to the class.

Fluent types must not be immutable. Don’t return a new instance on each setter call.

✅ DO use the JavaBean naming convention of get*, set*, and is*.

✅ DO include static methods if new model instances are required to be created from raw data. The static method names should be from<dataFormat>. For example, to create an instance of BinaryData from a string, include a static method called fromString in BinaryData class.

Model types sometimes exist only as an Azure service return type, and developers would never instantiate these. Often, these model types have API that is not user-friendly (in particular, overly complex constructors). It would be best for developers if they were never presented with this API in the first place, and we refer to these as ‘undesirable public API’.

✅ DO put model classes that are intended as service return types only, and which have undesirable public API into the .implementation.models package. In its place, an interface should be put into the public-facing .models package, and it should be this type that is returned through the public API to end users.

Examples of situations where this is applicable include when there are constructors or setters on a type which receive implementation types, or when a type should be immutable but needs to be mutable internally. The interface should have the model type name, and the implementation (within .implementation.models) should be named <interfaceName>Impl.

Enumerations

✅ DO use an enum for parameters, properties, and return types when values are known.

✅ DO use all upper-case names for enum (and ‘expandable’ enum) values. EnumType.FOO and EnumType.TWO_WORDS are valid, whereas EnumType.Foo and EnumType.twoWords are not.

✔️ YOU MAY use the ExpandableStringEnum type provided by Azure Core to define an enum-like API that declares well-known fields but which can also contain unknown values returned from the service, or user-defined values passed to the service. An example expandable enum is shown below:

public static final class OperationStatus extends ExpandableStringEnum<OperationStatus> {
    public static final OperationStatus NOT_STARTED = fromString("NOT_STARTED");
    public static final OperationStatus IN_PROGRESS = fromString("IN_PROGRESS");
    public static final OperationStatus SUCCESSFULLY_COMPLETED = fromString("SUCCESSFULLY_COMPLETED");
    public static final OperationStatus FAILED = fromString("FAILED");
    public static final OperationStatus USER_CANCELLED = fromString("USER_CANCELLED");

    /**
     * Creates or finds a {@link OperationStatus} from its string representation.
     * @param name A name to look for.
     * @return The corresponding {@link OperationStatus}.
     */
    public static OperationStatus fromString(String name) {
        return fromString(name, OperationStatus.class);
    }
}

✅ DO use an enum only if the enum values are known to not change like days of a week, months in a year etc.

✅ DO use ExpandableStringEnum provided by Azure Core for enumerations if the values are known to expand in future.

Using Azure Core Types

✅ DO make use of packages in Azure Core to provide behavior consistent across all Azure SDK libraries. This includes, but is not limited to:

• HttpClient, HttpPipeline, Response, etc. for http client, pipeline and related functionality.
• ClientLogger for logging.
• PagedIterable and PagedAsyncCollection for returning paged results.

See the Azure Core README for more details.

Using Primitive Types

⛔️ DO NOT create API that exposes the old Java date library (e.g. java.util.Date, java.util.Calendar, and java.util.Timezone), nor the newer date / time APIs that shipped in JDK 8 in the java.util.time package. All APIs must use the ThreeTenABP Date APIs.

⛔️ DO NOT create API that exposes the java.net.URL API. This API is difficult to work with, and more frequently gets in the users way rather than provide any real assistance. Instead, use the String type to represent the URL. When it is necessary to parse this String into a URL, and if it fails to be parsed (throwing a checked MalformedURLException), catch this internally and throw an unchecked IllegalArgumentException instead.

✅ DO wrap primitive types where appropriate to represent a meaningful domain entity even if the model type contains a single field. For example, a phone number is just a string, but creating a new type to wrap primitive String type can be more informative and represents a domain concept. It may also provide stronger guarantees and validation than just the primitive type.

public final class PhoneNumber {
    private String phoneNumber;

    public PhoneNumber setPhoneNumber(String phoneNumber) {
        ...
    }

    public String getPhoneNumber() {
        ...
    } 
}

Using Android-compatible Java APIs

✅ DO write client libraries in Java. This avoids forcing customers to depend on the Kotlin runtime in their applications.

✅ DO write client libraries using Java 8 syntax. Java 8 syntax constructs will be down-leveled using Java 8 language feature desugaring provided by Android Gradle Plugin 3.0.0+. This includes use of the following Java 8 language features:

• Lambda expressions
• Method references
• Type annotations (except TYPE_USE and TYPE_PARAMETER)
• Default and static interface methods
• Repeating annotations

⛔️ DO NOT use Java 8+ APIs. Some such APIs are able to be down-leveled using Java 8+ API desugaring provided by Android Gradle Plugin 4.0.0+. However many developers may not be using a sufficiently updated version of the plugin, and library desugaring injects additional code into the customer’s application, potentially increasing the APK size or method count. This includes use of the following Java 8+ APIs:

• Sequential streams (java.util.stream)
• java.time
• java.util.function
• Java 8+ additions to java.util.{Map,Collection,Comparator}
• Optionals (java.util.Optional, java.util.OptionalInt and java.util.OptionalDouble)
• Java 8+ additions to java.util.concurrent.atomic (new methods on AtomicInteger, AtomicLong and AtomicReference)
• ConcurrentHashMap

Exceptions

Error handling is an important aspect of implementing a client library. It is the primary method by which problems are communicated to the consumer. We convey errors to developers by throwing appropriate exceptions from our service methods.

✅ DO throw an exception when any HTTP request fails with an HTTP status code that is not defined by the service/Swagger as a successful status code.

✅ DO use unchecked exceptions. Java offers checked and unchecked exceptions, where checked exceptions force the user to introduce verbose try ... catch code blocks and handle each specified exception. Unchecked exceptions avoid verbosity and improve scalability issues inherent with checked exceptions in large apps.

In the case of a higher-level method that produces multiple HTTP requests, either the last exception or an aggregate exception of all failures should be produced.

✅ DO use the following standard Java exceptions for pre-condition checking:

⛔️ DO NOT create a new error type when a language-specific error type will suffice.

✅ DO specify all checked and unchecked exceptions thrown in a method within the JavaDoc documentation on the method as @throws statements.

✅ DO use the existing exception types present in the Azure Core library for service request failures. Avoid creating new exception types. The following list outlines all available exception types (with indentation indicating exception type hierarchy):

• AzureException: Never use directly. Throw a more specific subtype.
  • HttpResponseException: Thrown when an unsuccessful response is received with http status code (e.g. 3XX, 4XX, 5XX) from the service request.
    • ClientAuthenticationException: Thrown when there’s a failure to authenticate against the service.
    • DecodeException: Thrown when there’s an error during response deserialization.
    • ResourceExistsException: Thrown when an HTTP request tried to create an already existing resource.
    • ResourceModifiedException: Thrown for invalid resource modification with status code of 4XX, typically 412 Conflict.
    • ResourceNotFoundException: Thrown when a resource is not found, typically triggered by a 412 response (for PUT) or 404 (for GET/POST).
    • TooManyRedirectsException: Thrown when an HTTP request has reached the maximum number of redirect attempts.
• ServiceResponseException: Thrown when the request was sent to the service, but the client library wasn’t able to understand the response.
• ServiceRequestException: Thrown for an invalid response with custom error information.

✅ DO extend from one of the above exceptions defined in Azure Core when defining a new service-specific exception. Do not extend from RuntimeException directly.

✅ DO define exception type in a public package if the exception is thrown from a public API. Do not throw an exception that is defined as package-private or is defined in implementation package.

Authentication

Azure services use a variety of different authentication schemes to allow clients to access the service. Conceptually, there are two entities responsible in this process: a credential and an authentication policy. Credentials provide confidential authentication data. Authentication policies use the data provided by a credential to authenticate requests to the service.

✅ DO provide service client fluent builder APIs that accept an instance of the appropriate Azure Core credential abstraction, namely TokenCredential, BasicAuthenticationCredential, or AzureKeyCredential.

✅ DO support all authentication techniques that the service supports and that make sense in a mobile context. Service principal authentication generally does not make sense, for example.

TODO: Determine what are the supported authentication scenarios, which credential types will represent them and where will said types reside (Azure Core, Azure Identity, etc.)

⛔️ DO NOT persist, cache, or reuse security credentials. Security credentials should be considered short lived to cover both security concerns and credential refresh situations.

✅ DO use authentication policy implementations from the Azure Core library where available.

✅ DO define a public custom credential type which enables clients to authenticate requests using the custom scheme.

⚠️ YOU SHOULD NOT define custom credential types extending or implementing abstractions from Azure Core.

✅ DO provide credential types that can be used to fetch all data needed to authenticate a request to the service. If using a service-specific credential type, the implementation must be non-blocking and atomic.

✅ DO define custom credential types in the same namespace and package as the client, or in a service group namespace and shared package, not in Azure Core or Azure Identity.

✅ DO prepend custom credential type names with the service name or service group name to provide clear context to its intended scope and usage.

✅ DO append Credential to the end of the custom credential type name. Note this must be singular, not plural.

✅ DO define a constructor or factory for the custom credential type which takes in ALL data needed for the custom authentication protocol.

✅ DO define an update method which accepts all mutable credential data, and updates the credential in an atomic, thread safe manner.

⛔️ DO NOT define public settable properties or fields which allow users to update the authentication data directly in a non-atomic manner.

⚠️ YOU SHOULD NOT define public properties or fields which allow users to access the authentication data directly. They are most often not needed by end users, and are difficult to use in a thread safe manner. In the case that exposing the authentication data is necessary, all the data needed to authenticate requests should be returned from a single API which guarantees the data returned is in a consistent state.

✅ DO provide service client constructors or factories that accept all supported credential types.

Client libraries may support providing credential data via a connection string ONLY IF the service provides a connection string to users via the portal or other tooling. Connection strings are generally good for getting started as they are easily integrated into an application by copy/paste from the portal. However, connection strings are considered a lesser form of authentication because the credentials cannot be rotated within a running process.

✔️ YOU MAY provide a service client initializer that accepts a connection string if appropriate. The connection string must be provided as the first parameter to the initializer and must be named connectionString. When supporting connection strings, the documentation must include a warning that building credentials such as connection strings into a consumer-facing application is inherently insecure.

⛔️ DO NOT support initializing a service client with a connection string unless such connection string is available within tooling (for copy/paste operations).

⚠️ YOU SHOULD NOT support connection strings with embedded secrets. Android apps are not cryptographically secure and may be distributed to millions of devices. A developer should assume that any credential placed in an Android app is compromised.

When implementing authentication, don’t open up the consumer to security holes like PII (personally identifiable information) leakage or credential leakage. Credentials are generally issued with a time limit, and must be refreshed periodically to ensure that the service connection continues to function as expected. Ensure your client library follows all current security recommendations and consider an independent security review of the client library to ensure you’re not introducing potential security problems for the consumer.

If your service implements a non-standard credential system (that is, a credential system that is not supported by Azure Core), then you need to produce an authentication policy for the HTTP pipeline that can authenticate requests given the alternative credential types provided by the client library.

✅ DO provide a suitable authentication policy that authenticates the HTTP request in the HTTP pipeline when using non-standard credentials.

Namespaces

Java uses packages to group related types. Grouping services within a cloud infrastructure is common since it aids discoverability and provides structure to the reference documentation.

In Java, the namespace should be named com.azure.android.<group>.<service>[.<feature>]. All consumer-facing APIs that are commonly used should exist within this package structure. Here:

• <group> is the group for the service (see the list above)
• <service> is the service name represented as a single word
• <feature> is an optional subpackage to break services into separate components (for example, storage may have .blob, .files, and .queues)

✅ DO start the package with com.azure.android to indicate an Azure client library for Android.

✅ DO construct the package name with all lowercase letters (no camel case is allowed), without spaces, hyphens, or underscores. For example, Azure Key Vault would be in com.azure.android.security.keyvault - note that the two words ‘Key’ and ‘Vault’ are brought together to keyvault, instead of keyVault, key_vault, or key-vault. It may further be shortened if the shortened version is well-known in the community. For example, “Azure Media Analytics” would have a compressed service name of mediaanalytics, and “Azure Service Bus” would become servicebus.

✅ DO pick a package name that allows the consumer to tie the package to the service being used. The package does NOT change when the branding of the product changes. Avoid the use of marketing names that may change.

✅ DO use the following list as the group of services:

If the client library does not seem to fit into the group list, contact the Architecture Board to discuss the namespace requirements.

✅ DO place the management (Azure Resource Manager) API in the management group. Use the grouping <AZURE>.resourcemanager.<group>.<service> for the namespace. We do not expect many management APIs for Android, so this should be uncommon.

⛔️ DO NOT choose similar names for clients that do different things.

✅ DO register the chosen namespace with the Architecture Board. Open an issue to request the namespace. See the registered namespace list for a list of the currently registered namespaces.

⛔️ DO NOT allow implementation code (that is, code that doesn’t form part of the public API) to be mistaken as public API. There are two valid arrangements for implementation code:

1. Implementation classes can be placed within a subpackage named implementation.
2. Implementation classes can be made package-private and placed within the same package as the consuming class.

CheckStyle checks ensure that classes within an implementation package aren’t exposed through public API.

Example Namespaces

Here are some examples of namespaces that meet these guidelines:

• com.azure.android.data.cosmos
• com.azure.android.communication.common
• com.azure.android.storage.blob

Here are some namespaces that do not meet the guidelines:

• com.microsoft.azure.cosmosdb (not in the com.azure.android namespace and does not use grouping)
• com.azure.identity.activedirectory (not in the com.azure.android namespace)
• com.azure.mixedreality.kinect (the grouping is not in the approved list)

Support for Mocking

All client libraries must support mocking to enable non-live testing of service clients by customers. One of the key things we want to support is to allow consumers of the library to easily write repeatable unit-tests for their applications without activating a service. This allows them to reliably and quickly test their code without worrying about the vagaries of the underlying service implementation (including, for example, network conditions or service outages). Mocking is also helpful to simulate failures, edge cases, and hard to reproduce situations (for example: does code work on February 29th).

Below is an example of writing a mock unit test using the Mockito framework. For more details on using Mockito in the context of the Azure SDK for Android, refer to the unit testing wiki documentation.

TODO: Replace Java wiki entry for unit testing with one for Android.

public class UserPreferencesTest {
    @Test
    public void getThemeTest() {
        // create a mock instance of client
        ConfigurationClient configurationClient = mock(ConfigurationClient.class);

        // mock the client response
        when(configurationClient.getSetting("theme", null)).thenReturn(new ConfigurationSetting().setValue("light"));

        // wire the mock client to UserPreferences
        UserPreferences userPreferences = new UserPreferences(configurationClient);
        
        // assert the client response
        assertEquals(Theme.LIGHT, userPreferences.getTheme());
    }
}

✅ DO encapsulate access to Android OS APIs by way of an intermediate interface. This allows the runtime implementation to be swapped out for a test implementation in unit tests.

✅ DO support mocking to enable non-live testing of service clients (and by extension also model types, option types, etc) by customers.

✅ DO support mocking of all IO operations (including network and file operations).

Azure SDK Library Design

Supported Platforms

Android developers need to concern themselves with the runtime environment they are running in. The Android ecosystem is very fragmented, meaning that multiple versions and form factors are prevalent.

☑️ YOU SHOULD support all versions of Android starting with API level 15 (Ice Cream Sandwich).

✅ DO write client libraries in Java. This avoids forcing customers to depend on the Kotlin runtime in their applications.

✅ DO support Java 8 language features that do not require desugaring to work on older Android versions. For more information on the list of supported language features, please refer Use Java 8 language features and APIs.

Packaging

Gradle and Android Studio

All client libraries for Android standardize on the Gradle build tooling for build and dependency management. This section details the standard configuration that must be used in all client libraries.

✅ DO ship a build.gradle file for each client library, or for each module within that client library (e.g. Storage might have one each for blob, queue, and file).

✅ DO specify the package in the package’s AndroidManifest.xml to use the prefix com.azure.android.

✅ DO name Android library modules to be of the form azure-<group>-<service>, for example, azure-storage-blob. In cases where the client library has multiple children modules, set the root module name to be of the form azure-<group>-<service>-parent.

✅ DO specify the ext.publishName element to take the form Microsoft Azure Android client library for <service name>.

✅ DO specify the description element to be a slightly longer statement along the lines of This package contains the Microsoft Azure <service> client library.

Service-Specific Common Libraries

There are occasions when common code needs to be shared between several client libraries. For example, a set of cooperating client libraries may wish to share a set of exceptions or models.

✅ DO gain Architecture Board approval prior to implementing a common library.

✅ DO minimize the code within a common library. Code within the common library is available to the consumer of the client library and shared by multiple client libraries within the same namespace.

✅ DO store the common library in the same namespace as the associated client libraries.

The common library should use the common suffix. For example, if Azure Storage has a common library, it would be called azure-storage-common.

A common library will only be approved if:

• The consumer of the non-shared library will consume the objects within the common library directly, AND
• The information will be shared between multiple client libraries.

Let’s take two examples:

1. Implementing two Cognitive Services client libraries, we find a model is required that is produced by one Cognitive Services client library and consumed by another Cognitive Services client library, or the same model is produced by two client libraries. The consumer is required to do the passing of the model in their code, or may need to compare the model produced by one client library vs. that produced by another client library. This is a good candidate for choosing a common library.

2. Two Cognitive Services client libraries throw an ObjectNotFound exception to indicate that an object was not detected in an image. The user might trap the exception, but otherwise will not operate on the exception. There is no linkage between the ObjectNotFound exception in each client library. This is not a good candidate for creation of a common library (although you may wish to place this exception in a common library if one exists for the namespace already). Instead, produce two different exceptions - one in each client library.

Versioning

✅ DO be 100% backwards compatible with older versions of the same package.

✅ DO call the highest supported service API version by default.

✅ DO allow the consumer to explicitly select a supported service API version when instantiating the service client, by using the service client builder with a property called serviceVersion. This method must take a type implementing the ServiceVersion interface, named specifically for the service, but as generally as possible. For example, IdentityServiceVersion for Identity. For a service with multiple sub-services, such as Storage, if the services all share a common versioning system, StorageServiceVersion would suffice. If they did not, it would be necessary to have separate BlobServiceVersion, QueueServiceVersion, and FileServiceVersion enums.

✅ DO offer a getLatest() method on the enum that returns the latest service version. If a consumer doesn’t specify a service version, the builder will call getLatest() to obtain the appropriate service version.

✅ DO use the version naming used by the service itself in naming the version values in the enum. The standard approach takes the form V<year>_<month>_<day>, such as V2019_05_09. Being consistent with the service naming enables easier cross-referencing between service versions and the availability of features in the client library.

✅ DO introduce a new library (with new library names, new package names, and new type names) if you must do an API breaking change.

Breaking changes should happen rarely, if ever. Register your intent to do a breaking change with the Architecture Board. You’ll need to have a discussion with the language architect before approval.

Client Version Numbers

A consistent version number scheme allows consumers to determine what to expect from a new version of the library.

✅ DO use MAJOR.MINOR.PATCH format for the library version.

Use -beta.N suffix for beta package versions. For example, 1.0.0-beta.2.

✅ DO change the version number of the client library when ANYTHING changes in the client library.

✅ DO increment the patch version when fixing a bug.

⛔️ DO NOT include new APIs in a patch release.

✅ DO increment the major or minor version when adding support for a service API version.

✅ DO increment the major or minor version when adding a new method to the public API.

☑️ YOU SHOULD increment the major version when making large feature changes.

Dependencies

Dependencies bring in many considerations that are often easily avoided by avoiding the dependency.

• Versioning - Many programming languages do not allow a consumer to load multiple versions of the same package. So, if we have an client library that requires v3 of package Foo and the consumer wants to use v5 of package Foo, then the consumer cannot build their application. This means that client libraries should not have dependencies by default.
• Size - Consumer applications for mobile devices must be lightweight. Removing additional code (like dependencies) reduces the size.
• Licensing - You must be conscious of the licensing restrictions of a dependency and often provide proper attribution and notices when using them.
• Compatibility - Often times you do not control a dependency and it may choose to evolve in a direction that is incompatible with your original use.
• Security - If a security vulnerability is discovered in a dependency, it may be difficult or time consuming to get the vulnerability corrected if Microsoft does not control the dependency’s code base.

✅ DO depend on the Android Azure Core (com.azure.android.core) library for functionality that is common across all client libraries. This library includes APIs for HTTP connectivity, global configuration, logging, and credential handling.

⛔️ DO NOT be dependent on any other packages within the client library distribution package, with the exception of the following:

Dependency versions are purposefully not specified in this table. The definitive source for the dependency versions being used in all client libraries will be published in a separate document that is generated from the azure-sdk-for-android code repository. Transitive dependencies of these libraries, or dependencies that are part of a family of dependencies, are allowed.

TODO: Generate a definitive list of dependencies from the Android repository.

TODO: We should have a guideline around use of AndroidX libraries. Or if they’re treated the same as other external dependencies we should add them to the approved dependencies list.

TODO: Add a link to dependency whitelist. Also mention about transitive dependencies of those dependencies.

⛔️ DO NOT introduce new dependencies on third-party libraries that are already referenced from the top level build.gradle file, without first discussing with the Architecture Board.

⛔️ DO NOT specify or change dependency versions in your client library Gradle file. All dependency versioning must be centralized through the common parent build.gradle file.

⛔️ DO NOT include dependencies on pre-released or beta versions of external libraries. All dependencies must be approved for general use.

☑️ YOU SHOULD consider copying or linking required code into the client library in order to avoid taking a dependency on another package that could conflict with the ecosystem. Make sure that you are not violating any licensing agreements and consider the maintenance that will be required of the duplicated code. “A little copying is better than a little dependency” (YouTube).

⛔️ DO NOT depend on concrete logging, dependency injection, or configuration technologies (except as implemented in the Azure Core library). The client library will be used in applications that might be using the logging, DI, and configuration technologies of their choice.

Native code

Native code plugins cause compatibility issues and require additional scrutiny. Certain languages compile to a machine-native format (for example, C or C++), whereas most modern languages opt to compile to an intermediary format to aid in cross-platform support.

⚠️ YOU SHOULD NOT write platform-specific / native code. If you feel like you need to include native binaries in your library, contact the Azure SDK mobile team for advice.

✅ DO include binaries for all common Android architectures if your library includes platform-specific / native code. You should only include such native code in the Android library if:

• You distribute full source and it is compiled in the context of the customer code.
• You hide the implementation code behind a Java-based facade.
• You are doing so for performance reasons. No other reason is acceptable.

TODO: Develop and significantly expand upon our guidance for libraries with native (C/C++) code

Documentation

✅ DO ensure that anybody can clone the repo containing the client library and generate the full and complete JavaDoc output for the code, without any need for additional processing steps.

✅ DO include descriptive text of the method, as well as all parameters, the returned value (if any), all checked exceptions, as well as all unchecked exceptions. Failing to document unchecked exceptions means that users do not have any indication of how they can handle exceptional circumstances.

✅ DO include code samples in all class-level JavaDoc, and in relevant method-level JavaDoc.

⛔️ DO NOT hard-code the sample within the JavaDoc (where it may become stale). Put code samples in /src/samples/java and use the available tooling to reference them.

✅ DO follow the naming convention outlined below for naming samples tags:

• If a new instance of the class is created through build() method of a builder or through constructor: <packagename>.<classname>.instantiation
• For other methods in the class: <packagename>.<classname>.<methodName>
• For overloaded methods, or methods with arguments: <packagename>.<classname>.<methodName>#<argType1>-<argType2>
• Camel casing for the method name and argument types is valid, but not required.

Repository Guidelines

Documentation

General guidelines

✅ DO include your service’s content developer in the architectural review for your library. To find the content developer you should work with, check with your team’s Program Manager.

✅ DO follow the Azure SDK Contributors Guide (MICROSOFT INTERNAL)

✅ DO adhere to the Microsoft style guides when you write public-facing documentation. (MICROSOFT INTERNAL)

• Microsoft Writing Style Guide
• Microsoft Cloud Style Guide

Use the style guides for both long-form documentation like a README and the docstrings in your code.

☑️ YOU SHOULD attempt to document your library into silence. Preempt developers’ usage questions and minimize GitHub issues by clearly explaining your API in the docstrings. Include information on service limits and errors they might hit, and how to avoid and recover from those errors.

As you write your code, doc it so you never hear about it again. The fewer questions you have to answer about your client library, the more time you have to build new features for your service.

⛔️ DO NOT include version details when specifying Gradle dependency statements.

Samples

Code samples are small applications that demonstrate a certain feature that is relevant to the client library. Samples allow developers to quickly understand the full usage requirements of your client library. Code samples shouldn’t be any more complex than they needed to demonstrate the feature. Don’t write full applications. Samples should have a high signal to noise ratio between useful code and boilerplate code for non-related reasons.

✅ DO include code samples alongside your library’s code within the repository. The samples should clearly and succinctly demonstrate the code most developers need to write with your library. Include samples for all common operations. Pay attention to operations that are complex or might be difficult for new users of your library. Include samples for the champion scenarios you’ve identified for the library.

✅ DO place code samples within the /src/samples/java directory within the client library root directory. The samples will be compiled, but not packaged into the resulting jar.

TODO: Add section about making code runnable through means similar to a Java class’ main method.

✅ DO use the latest coding conventions when creating samples. Make liberal use of Java 8 syntax and APIs (for example, diamond operators) as they remove boilerplate from your samples and highlight you library, as long as they are included in Android’s Java 8 supported features list for the Gradle 3.0.0+ plugin.

✅ DO compile sample code using the latest major release of the library. Review sample code for freshness. At least one commit must be made (to update dependencies) to each sample per semester.

✅ DO ensure that code samples can be easily grafted from the documentation into a users own application. For example, don’t rely on variable declarations in other samples.

✅ DO write code samples for ease of reading and comprehension over code compactness and efficiency.

✅ DO ensure that samples can run in Android Studio for Windows, macOS and Linux. Don’t use a non-standard developer toolchain.

✅ DO build and test your code samples using the repository’s continuous integration (CI) to ensure they remain functional.

⛔️ DO NOT combine multiple operations in a code sample unless it’s required for demonstrating the type or member. For example, a Cosmos DB code sample doesn’t include both account and container creation operations. Create a sample for account creation, and another sample for container creation.

Combined operations require knowledge of additional operations that might be outside their current focus. The developer must first understand the code surrounding the operation they’re working on, and can’t copy and paste the code sample into their project.

Java Best Practices for Android

This section introduces guidelines for fundamental Java development design decisions that are used throughout the Azure SDK for Android.

Naming Patterns

Using a consistent set of naming patterns across all client libraries will ensure a consistent and more intuitive developer experience. This section outlines good practices for naming that must be followed by all client libraries.

✅ DO prefer succinctness over verbosity in method and class names, except when readability is impacted. A few examples include:

• A class may want to return an identifier to a user. There is no additional value in the fully-qualified getIdentifier() compared with the shorter and equally-descriptive getId().
• A method called getName() is short, but may leave some doubt in the users mind about which name is being represented. Instead, naming this method getLinkName() will remove all doubt from the users mind, and without substantial additional verbosity. Similarly, in the case of getId() above, always choose to specify the identifier name if there is any likelihood of confusion about which identifier is being referenced. For example, use getTenantId() rather than getId(), unless it is completely unambiguous as to which identifier is being referenced.

⛔️ DO NOT fully uppercase acronyms. APIs must take the form of getHttpConnection() or getUrlName() rather than getHTTPConnection() or getURLName().

✅ DO use service-specific acronyms sparingly in API. Whereas most users will accept a method including Http or Url in the name, most users will not know what Sas or Cpk mean. Where possible (without breaking the succinctness over verbosity requirement above), expansion of acronyms, or at the very least sufficient documentation at class and method levels to describe the acronym, must be considered.

✅ DO use the correct naming for ‘host’ vs ‘hostname’. ‘hostname’ is the host name without any port number, whereas ‘host’ is the hostname with the port number.

⛔️ DO NOT use camel case on words that are commonly accepted in their combined form. For example, ‘hostname’ should be spelt as hostname rather than hostName, and ‘username’ should be spelt as username rather than userName.

⛔️ DO NOT name interface types with an ‘I’ prefix, e.g. ISearchClient. Instead, do not have any prefix for an interface, preferring SearchClient as the name for the interface type in this case.