Cross-check Azure guidelines with ARM guidelines to ensure consistency

We should make sure the Azure guidelines are consistent with the RP guidelines — meaning that these guidelines should not contradict anything in the RP guidelines, but the RP guidelines can be more strict.

Thanks for taking this on!

I reached out to @vladimirjoanovic for a pointer to the RP/ARM API Guidelines. Here's his response:

Our guidance/RPC is on aka.ms/armwiki and aka.ms/rpapiv2

Using information from:

• OpenAPI Specifications Authoring - Automated Guidelines and
• OpenAPI Specifications Authoring - Manual Guidelines

I recommend that we add the following to our Azure API Guidelines:


• Property names must use lowerCamelCase style. (R3014, R3016)
• For a given path with PUT, GET and PATCH operations, the schema of the response should be the same. (R3007)
• Request body of a Patch Operation must not have any required properties. (R2016)
• The schema for the items of the value property should be the same as the response schema of a GET on an individual resource. (R4019)
• The request & response('200') schema of the PUT operation must be same. (R2017)
• Plural names in parameters and model properties MUST only be used to represent collections

We should add the following to ConsiderationsForServiceDesign

• Terminology in API defn and Azure Portal MUST be the same

I've also compiled a list of these guidelines to be included in a forthcoming Azure API Definition Style Guide.

There was a question raised in a recent API review on consistency of the Azure API guidelines vs ARM guidelines on whether URL path segments should be treated as case-sensitive or case-insensitive.

Today I discovered something in the ARM API guidelines that might have led to this impression. See this section of the ARM API guidelines, where it says:

The resource group names and resource names should be matched case insensitively. That means, for example, if a user creates a resource in resource group "rG1", and then calls a read operation on "RG1", the same resource should be returned even though the casing differs.

Note that resource group names and resource names are user-specified path segments (path parameters).

The Azure API guidelines say:

DO treat service-defined URL path segments as case-sensitive.

and goes on to say:

Some customer-provided path segment values may be compared case-insensitivity if the abstraction they represent is normally compared with case-insensitivity.

So I don’t believe there is any conflict here.