Protocol Methods Quickstart with AutoRest

Before you Start

Java Azure SDK Design Guidelines is the overall design guideline of the data-plane SDK.

Generate SDK

You can choose from

1. Python script, Java developer environment required
2. Azure pipeline

to create your first data-plane SDK.

Use Python script for first-time code generation

A Python script in Azure SDK for Java can help generate a minimal data-plane client SDK from OpenAPI 2.0 specification.

Please see Working with AutoRest for the installation of autorest CLI. It also requires the installation of Node.js 10 or above, Java 8 or above, and Python 3.

If you are new to Java development environment, see Java Development Environment for details.

Required options from user:

• input-file: URL to OpenAPI 2.0 specification JSON as input file.
• service: Service name under sdk/, sample: storage.
• module: Module name under sdk/<service>/, sample: azure-storage-blob.
• credential-types: Credential types, sample: tokencredential for AAD credential for OAuth 2.0 authentication.
• credential-scopes: OAuth 2.0 scopes, required if credential-types includes tokencredential.
• title: Optional for client name. The name should always ends with "Client", sample: BlobClient, which results in BlobClientBuilder as builder class.

For service, it is usually your service name in REST API specifications. For instance, if the JSON is under specification/storage, the service would normally be storage.

For module, please refer to Namespace in Java Guideline. For example, if the namespace is com.azure.storage.blob, the module should be azure-storage-blob.

As an example,

python eng/mgmt/automation/generate_data.py --input-file=https://github.com/Azure/azure-rest-api-specs/blob/main/specification/purview/data-plane/Azure.Analytics.Purview.Account/preview/2019-11-01-preview/account.json --service=purview --module=azure-analytics-purview-account --credential-types=tokencredential --credential-scopes=https://purview.azure.net/.default

This will generate the SDK under sdk/purview/azure-analytics-purview-account. And your follow-up work will mostly happen in this SDK folder.

The Python script also builds the generated project. It is possible that the verification fails due to Java code quality requirements. See Build section on how to fix.

Use Azure pipeline for first-time code generation

There is an internal pipeline java - client generation - data, which invokes the the Python script, generate the code, and create pull request of the generated SDK.

It takes similar input parameters as the script, e.g. INPUT_FILE variable for input-file option, SERVICE and MODULE variable for service and module option.

A draft pull request will be created at pull requests, named as [Automation] Generate Data-plane SDK for <module>.

Follow-up code generation

An AutoRest configuration file is generated at swagger/README_SPEC.md during the first-time code generation. You can now edit it, and generate code through this configuration file.

As an example,

autorest --use=@autorest/java@4.0.43 swagger/README_SPEC.md

It is advised to use the latest version of autorest/java extension (see AutoRest.Java Release).

The possible settings can be found either from autorest --help --java, or from AutoRest.Java readme.

A few commonly used settings:

• title and service-name is used to specify the entry of your SDK. Usually it be as e.g. title=PurviewAccountClient and service-name=PurviewAccount.
• service-versions is a list of compatible api-version for the SDK. If other api-version of your service is compatible with this OpenAPI 2.0 specification, you can add them to this list.
• polling if the polling strategy of your long-running operation is not covered from pre-defined polling strategies.

Build

See Building and Adding a Module.

Here is the list of files that you are required to modify/confirm for your new module.

• /eng/versioning/version_client.txt for versioning
• /sdk/<service>/pom.xml for project
• /sdk/<service>/ci.yml for CI

The Python script automatically created/modified these files for you. However it is still advised that you double check them.

Install for Local Test

See Building. Install SDK to local maven repository: mvn install -f sdk/<service>/<module>/pom.xml -Dgpg.skip -Drevapi.skip -DskipTests

See Maven Getting Start Guide, if you would like to create a client that uses your SDK. See sdk/<service>/<module>/README.md for adding the SDK to dependency.

Improve SDK documentation

There is many information about the SDK that AutoRest will never know. These can only be provided by a contributor.

README

A minimal README.md is generated by AutoRest. Your first task will be improving it.

You might want to modify [product_documentation] to point to your service documentation.

Samples

A blank Java sample file is generated as ReadmeSamples.java, which is synchronized with your README (see JavaDoc with CodeSnippet).

A collection of generated Java sample files (based on x-ms-examples in OpenAPI specs) is generated under <module>.generated package. They might not be directly usable as runnable sample codes, however you should get the basic idea on how code works, and may even modify some to be runnable.

Tests

A blank Java test file is generated as ClientTests.java, with set-up code that prepares the environment for test record and playback. You can follow-up with your test codes.

Improve SDK code

ClientBuilder, Client, AsyncClient is the user-facing API surface that you might be interested to improve. See Partial Update.

Appendix

Java Development Environment and AutoRest

Windows

Download Java, install.

Download Maven, unpack, set to PATH.

Download Node.js, install.

Install AutoRest with npm install -g autorest in command line.

Optional for Git and Python:

• Download Git, install.
• Download Python, install.

Linux with APT

sudo apt -y install openjdk-17-jdk

sudo apt -y install maven

curl -sL https://deb.nodesource.com/setup_16.x | sudo bash -
sudo apt -y install nodejs

npm install -g autorest

Partial Update

Since autorest/java@4.0.42 and with partial-update option, you can in-place modify the generated code, and AutoRest.Java will keep it intact when it re-generates the SDK.

The user-facing API is of pattern:

FooClient client = new FooClientBuilder()
    .endpoint(...)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildFooClient();

FooAsyncClient asyncClient = new FooClientBuilder()
    .endpoint(...)
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildFooAsyncClient();

And the classes involved is FooClient, FooAsyncClient, and FooClientBuilder.

All of these classes can be customized in-place, to enhance the usability of the SDK, or to add new feature.

You can add new class variable and new class method to these classes, and with partial-update option in swagger/README_SPEC.md, new code generated via AutoRest will not override your change.

For modifying the signature or the implementation of a class method, please remove the @Generated annotation, so AutoRest.Java can recognize that you have modified the method.

If you would like to remove a class method, simply make the method package private, so it is not exposed to customer. Also you need to remove the @Generated annotation.

It is advised that you keep the modifications simple. If certain feature requires complicated code, it is better to put the implementation code in some other classes within implementation package, and only add the public class method and invocation in these Client or ClientBuilder classes.