Skip to content

Commit 953c881

Browse files
josefreemikekistler
josefree
and
mikekistler
authored
Update README.md (Azure#18936)
* Update README.md enhance folder structure guidance * Update README.md * minor update to "preview" and "stable" section * add further clarification to service group folder * minor update of the wording * Update README.md add future description of service group folder structure. * Update README.md some minor updates * Update README.md Co-authored-by: Mike Kistler <[email protected]> * Update README.md * Update README.md Co-authored-by: Mike Kistler <[email protected]>
1 parent 5ee062a commit 953c881

File tree

1 file changed

+140
-46
lines changed

1 file changed

+140
-46
lines changed

‎README.md

+140-46
Original file line numberDiff line numberDiff line change
@@ -5,37 +5,63 @@
55
This repository is the canonical source for REST API specifications for Microsoft Azure.
66

77
## Getting started
8-
If you're a Microsoft employee looking for information about all of the repositories and steps in the pipeline, go to the [Azure SDK - Internal Wiki](https://aka.ms/jointhesdk). Make sure to [join the Github Azure organization](http://aka.ms/azuregithub) to get access to that wiki repo. If any trouble with access, please submit a support request using this [form](https://aka.ms/swaggerfeedback).
8+
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.
99

10-
<b>Latest improvement:</b><i> Microsoft employees can try out our new experience at [OpenAPI Hub](https://aka.ms/openapihub) - online experience for using our validation tools and finding your workflow.</i>
10+
External Contributors can read [Getting Started with Azure API Specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/getting-started-with-azure-api-specifications.md).
1111

12-
External Contributors can get started [here](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/Getting%20started%20with%20OpenAPI%20specifications.md)
1312

14-
Please check the [announcements page](https://github.com/Azure/azure-rest-api-specs/wiki/Announcements) for any new updates since your last visit.
13+
14+
<!--Please check the [announcements page](https://github.com/Azure/azure-rest-api-specs/wiki/Announcements) for any new updates since your last visit.-->
15+
16+
### Terminology
17+
18+
- **Offerings**, **Skus**, and **Features** - These are distinct entities represented in Eco Manager and Service Tree. While the Offering/Sku/Feature entities and hierarchy represent the externally marketed product, **service/components** entities in service tree represent corresponding engineering entities that together power these external products. Refer to [Product Taxonomy](https://dev.azure.com/msazure/AzureWiki/_wiki/wikis/AzureWiki.wiki/40783/Service-Tree-Product-Taxonomy) for details.
19+
20+
- **Resource Provider** - When a service onboard 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)*
21+
1522

1623
## Directory Structure
1724

25+
1826
The structure of the directory should strictly follow these rules:
1927

20-
1. **Profile**: The profile holder contains the profiles' definition MD files. these files will contain information and references to the snapshots of the RPs' Resource types or Dataplane API versions that represent a specific profile.
28+
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.
29+
30+
2. **Specification**: This folder is the root folder for all Specs (Management Plane and Data Plane) related documents.
2131

22-
1. **Specification**: This folder is the root folder for all Specs (Management and Dataplane) related docs.
32+
3. **{RP-Name} Folders** - each resource provider should have at least one separate folder.
33+
> If multiple folders are required? It depends on the following considerations:
34+
>
35+
> - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities?
36+
> - 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?
37+
> - 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 need to be referred cross RP folders should to be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types).
38+
> - 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).
2339
24-
1. **{RP-Name} Folders** - each RP will have a separate folder
40+
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.
2541

26-
1. **'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) . The autorest configuration file (`readme.md`) for the RP should be inside this folder
2742

28-
1. **'preview' and 'stable' Folders**: Varying levels of stability exist in our repository. Each API Version folder should be categorized as either still accepting breaking changes, or no longer accepting breaking changes. This is not a direct analog for whether or not an API Version has the "-preview" suffix or not. SDKs that are generated from 'preview' folder items should indicate to their customers in the most idiomatic way that breaking changes may still be coming.
43+
5. **'cadl' Folders**: this folder holds CADL specs of either `resource-manager` or `data-plane`. CADL 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 CADL repo: [CADL tutorial](http://aka.ms/cadlTutorial). You can also ask questions for provide feedback in the teams channel [CADL 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).
2944

30-
1. **API versions**: this folder will be the direct child of the category folder. there will be one such folder per resource type or dataplane service version. This folder will contain the OpenAPI validation Specs (Swaggers previously) and the examples folder.
3145

32-
1. **Examples**: 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.
46+
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).
3347

34-
1. **Notes**:
35-
- folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers.
36-
- generic folder names should be lower-case
37-
- proper-name/product name/namespace folders can be PascalCased (ie, "KeyVault")
38-
- files are whatever case you think is good for your soul.
48+
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 hold API versions of a GAed service and all GAed components.
49+
50+
> 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.
51+
> - 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.
52+
>
53+
> - 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).
54+
55+
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.
56+
57+
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.
58+
59+
> Note: some general guidance for folder names, file names under `specification`:
60+
>
61+
> - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers.
62+
> - Generic folder names should be lower-case
63+
> - Namespace folders can be PascalCased (ie, "KeyVault")
64+
> - Files are whatever case you think is good for your soul.
3965
4066

4167
The structure should appear like so:
@@ -44,45 +70,113 @@ The structure should appear like so:
4470
\---specification
4571
| +---automation
4672
| | \---resource-manager
47-
| | \---Microsoft.Automation
48-
| | \---stable
49-
| | \---2015-10-31
50-
| | \---examples
73+
| | +---Microsoft.Automation
74+
| | | \---stable
75+
| | | \---2015-10-31
76+
| | | \---examples
77+
| | \---readme.md
5178
| +---batch
5279
| | +---data-plane
53-
| | | \---Microsoft.Batch
54-
| | | +---stable
55-
| | | | +---2015-12-01.2.2
56-
| | | | +---2016-02-01.3.0
57-
| | | | +---2016-07-01.3.1
58-
| | | | +---2017-01-01.4.0
59-
| | | | \---examples
60-
| | | \---preview
61-
| | | \---2017-05-01.5.0
80+
| | | +---stable
81+
| | | | +---2016-07-01
82+
| | | | | \---examples
83+
| | | | \---2017-01-01
84+
| | | | \---examples
85+
| | | +---preview
86+
| | | | \---2017-05-01-preview
87+
| | | | \---examples
88+
| | | \---readme.md
6289
| | \---resource-manager
63-
| | \---Microsoft.Batch
64-
| | +---stable
65-
| | | +---2015-12-01
66-
| | | +---2017-01-01
67-
| | | \---examples
68-
| | \---2017-05-01
69-
| | \---examples
70-
| +---billing
90+
| | +---Microsoft.Batch
91+
| | | \---stable
92+
| | | +---2015-12-01
93+
| | | | \---examples
94+
| | | +---2017-01-01
95+
| | | | \---examples
96+
| | | \---2017-05-01
97+
| | | \---examples
98+
| | \---readme.md
99+
| +---playfab
71100
| \---resource-manager
72-
| \---Microsoft.Billing
73-
| \---stable
74-
| | +---2017-02-27-preview
75-
| | \---examples
76-
| +---preview
77-
| \---2017-04-24-preview
78-
| \---examples
79-
\--- readme.md
101+
| +---Microsoft.Playfab
102+
| | +---cadl
103+
| | | \---playfab.cadl
104+
| | +---stable
105+
| | | \---2017-02-27-preview
106+
| | | \---examples
107+
| | \---preview
108+
| | \---2017-04-24-preview
109+
| | \---examples
110+
| \---readme.md
80111
```
112+
### Folder Structure for Service Group
113+
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 collaboaration, especially supporting:
114+
115+
- To collect API definition of multiple components/services with different versioning cycle in one rp folder
116+
- To share some common entity types among services or components under the same rp folder.
117+
118+
In the following folder structure sample, there is only 'resource-manager' folder. There could be a similar folder structure under 'data-plane' folder, while the sub-component/sub-service folders may not be the same.
119+
120+
Ensure to consult [API Spec and Tooling Support](https://teams.microsoft.com/l/channel/19%3af1b9607b948840cca8b7852ed6bb1713%40thread.skype/General?groupId=a5e9b41d-1b0a-471d-a170-8ce202fa30b1&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47) for the first time creating the folder structure or if you want to change current folder structure.
121+
122+
```bash
123+
.
124+
\---specification
125+
| +---compute
126+
| | \---resource-manager
127+
| | +---Microsoft.Compute
128+
| | | +---compute
129+
| | | | \---stable
130+
| | | | \---2021-11-01
131+
| | | | +---compute.json
132+
| | | | +---runCommands.json
133+
| | | | \---examples
134+
| | | +---sku
135+
| | | | \---stable
136+
| | | | \---2021-07-01
137+
| | | | +---skus.json
138+
| | | | \---examples
139+
| | | +---disk
140+
| | | | \---stable
141+
| | | | \---2021-12-01
142+
| | | | +---disk.json
143+
| | | | \---examples
144+
| | | +---gallery
145+
| | | | \---stable
146+
| | | | \---2021-10-01
147+
| | | | +---gallery.json
148+
| | | | \---examples
149+
| | | +---sharedgallery
150+
| | | | \---stable
151+
| | | | \---2021-07-01
152+
| | | | +---sharedGallery.json
153+
| | | | +---communityGallery.json
154+
| | | | \---examples
155+
| | | +---cloudService
156+
| | | | \---stable
157+
| | | | \---2021-03-01
158+
| | | | +---cloudService.json
159+
| | | | \---examples
160+
| | | \---common-types
161+
| | | \---v1
162+
| | | \---entity-types.json
163+
| | |
164+
| | \---readme.md
165+
```
166+
167+
If the AutoRest configuration file (aka. the readme.md) is placed out of sub-service/sub-component folders, then there will be only one SDK package that holds all sub-services/sub-components. If the file is placed in each sub-service/sub-component folder, then there will be separate SDK packages of each sub-service/sub-component. Ensure to consult [Azure SDK ArchBoard](https://dev.azure.com/azure-sdk/internal/_wiki/wikis/internal.wiki/667/Azure-SDK-Archboard-Review) for SDK packaging strategy when consolidating AutoRest configuration file for SDK generation.
168+
169+
### common-types
170+
171+
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.
172+
173+
. Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example.
81174

82-
Currently, the specifications are expected to be in Swagger JSON format
83175

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

179+
External Contributors can read [Getting Started with Azure API Specifications](https://github.com/Azure/azure-rest-api-specs/blob/master/documentation/getting-started-with-azure-api-specifications.md).
180+
87181
---
88182
_This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments._

0 commit comments

Comments
 (0)