Skip to content

Commit

Permalink
Update main repo README: links to new docs + formatting (#25565)
Browse files Browse the repository at this point in the history 
Co-authored-by: Mariana Rios Flores <[email protected]>
  • Loading branch information
@maririos
Konrad Jamrozik and maririos authored Aug 30, 2023
1 parent e1faef4 commit ac44b88
Showing 1 changed file with 17 additions and 19 deletions.
36 changes: 17 additions & 19 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,13 @@

## Description

This repository is the canonical source for REST API specifications for Microsoft Azure.
This repository is the canonical source for REST API specifications for Microsoft Azure. You can learn more about it [here](https://eng.ms/docs/products/azure-developer-experience/design/api-specs-pr/api-repos).

## Getting started
If you're a Microsoft employee looking for information about all of the repositories and steps for Azure SDK Libraries Releases, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk). To get access to the wiki, you need to request access to the [Azure SDK Release Partners](https://aka.ms/azsdk/join/azuresdkpartners) security group. This is a MyAccess group and requests to join will need to be approved by your manager.

External Contributors can read [Getting Started with OpenAPI Specifications](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md).

If you're a Microsoft employee looking for information about all of the repositories and steps for Azure SDK Libraries Releases, go to the [aka.ms/azsdk/join](https://aka.ms/azsdk/join).

External Contributors can read [Getting Started with OpenAPI Specifications](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md).

<!--Please check the [announcements page](https://github.com/Azure/azure-rest-api-specs/wiki/Announcements) for any new updates since your last visit.-->

Expand All @@ -19,10 +18,8 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt

- **Resource Provider** - When a service onboards new functionality onto ARM, it is required to complete [Resource Provider Registration](https://armwiki.azurewebsites.net/rp_onboarding/ResourceProviderRegistration.html). For existing **Resource Provider to Service Mapping**, refer to [Match resource provider to service](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service)*


## Directory Structure


The structure of the directory should strictly follow these rules:

1. **Profile**: The profile folder contains the profiles' definition files. The profile definition targets for hybrid applications that could run on Azure Stack general availability versions and Azure Cloud.
Expand All @@ -32,30 +29,29 @@ The structure of the directory should strictly follow these rules:
3. **{RP-Name} Folders** - each resource provider should have at least one separate folder.
> If multiple folders are required? It depends on the following considerations:
>
> - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities?
> - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future?
> - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types).
> - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex).
> - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities?
> - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future?
> - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types).
> - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex).
RP folders may contain resource manager or data plane TypeSpec "specs". TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the TypeSpec repo: [TypeSpec tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the internal Teams channel [TypeSpec Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47).

For more information about the structure of TypeSpec files in the repo see [TypeSpec repo structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md).

5. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present.

6. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting).

4. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present.

5. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting).

6. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components.
7. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components.

> How's the Azure Breaking Change Policy apply to API specs in `preview` and `stable` folders? In fact, it is more relevant to if the repo is public or private.
> - API specs with components or resource types in Private Preview, or Limited Public Preview (behind [AFEC](https://armwiki.azurewebsites.net/rp_onboarding/afec/FeatureExposureControl.html) or managing visible subscriptions) are better to launch PR review in the private repository, aka., [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr). And these API specs are free of breaking changes.
>
> - On the other hand, everything public in the main branch of the public repository, aka., [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), no matter in the `preview` folder or in the `stable` folder, should be treated as contract with Azure customers, must follow [Azure Breaking Changes Policy](http://aka.ms/AzBreakingChangesPolicy).
7. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder.
8. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder.

8. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples.
9. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples.

> Note: some general guidance for folder names, and file names under `specification`:
>
Expand Down Expand Up @@ -111,7 +107,9 @@ The structure should appear like so:
| | \---examples
| \---readme.md
```

### Folder Structure for Service Group

If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting:

- To collect API definition of multiple components/services with different versioning cycle in one rp folder
Expand Down Expand Up @@ -172,10 +170,10 @@ If the AutoRest configuration file (aka. the readme.md) is placed out of sub-ser

Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the enitity type sharing cross components or services under the same rp folder.

. Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example.

Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example.

## Next steps

The next step in the process after a spec is completed is to generate SDKs and API reference documentation. If you're a Microsoft employee, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk) for more information.

External Contributors can read [Getting Started with OpenAPI Specifications](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/Getting%20started%20with%20OpenAPI%20specifications.md).
Expand Down

0 comments on commit ac44b88

Please sign in to comment.