lucashuet93 · ross-p-smith · Sep 18, 2023 · Sep 7, 2023
diff --git a/README.md b/README.md
@@ -47,45 +47,11 @@ The Application Insights Instrumentation Key is stored as a Key Vault secret, wh
 
 The values stored in the base API Management configuration correspond to the dev environment. Importantly, when the configuration is applied to the prod environment, API Management should connect to the production environment's supporting resources, not the ones in the dev environment. The [configuration.prod.yaml](./configuration.prod.yaml) file is used to override resource IDs to point at the prod environment's Key Vault, Log Analytics, and Application Insights resources. It additionally contains overrides for the Swagger Petstore backend, but the same url is currently used for both environments.
 
-## Spec Transfer Process
-
-The backend APIs fronted by API Management may be developed by a separate team in a different repository. The API Management configuration stored in `/apim_templates` is not a static set of files, and instead must change over time to accommodate changes in the backend APIs. As backend APIs change, their corresponding Open API Specs change as well. As new specs are created by the backend API team, the API Ops team must ingest the files and generate the required changes in API Management.
-
-As new versions of a spec become available, new versions or revisions to an existing version should be created for the corresponding API Management API. Versions and revisions are captured in API Ops as entirely new folders within `/apim_templates/apis`. For reference, the Swagger Petstore API that has 3 versions (each with different spec) has the following corresponding folders in `/apim_templates/apis`:
-
-- `swagger-petstore/`
-- `swagger-petstore-v2/`
-- `swagger-petstore-v3/`
-
-When a new version of a spec is released, a decision must be made [whether the change is breaking or not](https://learn.microsoft.com/en-us/azure/api-management/api-management-versions#versions-and-revisions). If the change is breaking, a new folder should be created in `/apim_templates/apis` that corresponds to the next available **version**. For the Swagger Petstore API, a new folder named `swagger-petstore-v4` would be created. If the change is not breaking, a new folder should be created in `/apim_templates/apis` that corresponds to the next available **revision** for the version that the spec targets. For the Swagger Petstore API, if the spec referred to a revision to `v3` of the API, a new folder named `swagger-petstore-v3;rev=2` would be created. A subsequent revision would result in a new folder named `swagger-petstore-v3;rev=3`.
-
-API Ops expects each API folder to contain the following files:
-
-- `apiInformation.json`, which contains the API configuration data
-- `policy.xml`, which contains the API Policy applied to all API Operations
-- `specification.yaml`, which contains the Open API Spec for the API
-
-The `specification.yaml` file for a new version or revision will be the spec that is released by the backend API team. The `apiInformation.json` and `policy.xml` files from the previous versions or revisions should be used as templates to build the `apiInformation.json` and `policy.xml` files necessary for the newly created `/apim_templates/apis` folder. Generally, a new version's `apiInformation.json` will be nearly identical to the previous version's `apiInformation.json` file, with the `apiVersion` property updated. Similarly, a new revision's `apiInformation.json` will be nearly identical to the previous revision's `apiInformation.json` file, with the `apiRevision`, `apiRevisionDescription`, and `isCurrent` properties updated (only one revision may be current for each version). Additional properties may be updated, if necessary.
-
-In addition to the APIM API configuration itself, the API may need to be associated with existing Products. API Ops Products are stored in the `/apim_templates/products` folder, where each Product has it's own directory that corresponds to its name. API Ops uses a few files to define Product configuration, but uses the `/apim_templates/products/{PRODUCT_NAME}/apis.json` file to set the APIs the Product should be associated with. Each `apis.json` file contains an array of API names that correspond to the folders in `/apim_templates/apis`. The name of the newly created `/apim_templates/apis` folder should be added to `apis.json` for each of the Products the new API version/revision should be associated with.
-
-The `backends`, `diagnostics`, `loggers`, and `named values` folders in `/apim_templates` folder do not need to be updated on new spec changes. The url for the backend API does not change on spec updates and the monitoring configuration for the previous versions/revisions of the API will be applied to the new version/revision as well.
-
-In total, when a new version or revision is created, a new folder should be created in `/apim_templates/apis` that includes the following files:
-
-- `/apis/{API_NAME}/apiInformation.json`
-- `/apis/{API_NAME}/policy.xml`
-- `/apis/{API_NAME}/specification.yaml`
-
-And the `apis.json` file should be updated for each associated Product:
-
-- `/products/{PRODUCT_NAME}/apis.json`
-
-Once the new folder and files are added and updated, the new configuration can be published to API Management.
-
 ## Decisions made
+
 The following decisions have been made around this sample repository
 - [Service Level vs API Level Observability](./docs/adr-01.md)
+- [Spec Transfer Process](./docs/adr-02.md)
 
 ## Running the Project
 
@@ -170,19 +136,5 @@ The extractor is not used to pull configuration changes into the [/apim_artifact
 To run the extractor locally, open Bash in the VSCode terminal and run `make extract-dev`. Configuration changes will be extracted into an ignored /temp folder.
 
 ### Testing your API from Visual Studio Code
-The DevContainer will install two tools that will you help you test your APIs all from your IDE.
- - [Azure API Management Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-apimanagement)
- - [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
-
-1. Use the APIM extension to Copy APIM Subscription Key by right clicking on the APIM instance
-
-![Copy Subscription Key](assets/GetSubscriptionKey.png)
-
-2. Copy this value into the [Settings](/.vscode/settings.json) in the correct environment.
-
-3. Navigate to the API and "Test Operation" and it will generate you a REST file.
-![Test Operation](assets/TestOperation.png)
-
-4. When you have the editor open with a .http file you will be able to chose which `environment` in the bottom corner of VSCode. This will make sure you subscription key is used when you make a request to APIM ![Chose Environment](assets/ChoseEnvironment.png)
 
-Happy Testing!
+Please read [this guide](docs/testing.md) to read how you can test your APIs from within the DevContainer.
diff --git a/docs/adr-02.md b/docs/adr-02.md
@@ -0,0 +1,39 @@
+# Spec Transfer Process
+
+## Context
+
+The backend APIs fronted by API Management may be developed by a separate team in a different repository. The API Management configuration stored in `/apim_templates` is not a static set of files, and instead must change over time to accommodate changes in the backend APIs. As backend APIs change, their corresponding Open API Specs change as well. As new specs are created by the backend API team, the API Ops team must ingest the files and generate the required changes in API Management.
+
+## Approach
+
+As new versions of a spec become available, new versions or revisions to an existing version should be created for the corresponding API Management API. Versions and revisions are captured in API Ops as entirely new folders within `/apim_templates/apis`. For reference, the Swagger Petstore API that has 3 versions (each with different spec) has the following corresponding folders in `/apim_templates/apis`:
+
+- `swagger-petstore/`
+- `swagger-petstore-v2/`
+- `swagger-petstore-v3/`
+
+When a new version of a spec is released, a decision must be made [whether the change is breaking or not](https://learn.microsoft.com/en-us/azure/api-management/api-management-versions#versions-and-revisions). If the change is breaking, a new folder should be created in `/apim_templates/apis` that corresponds to the next available **version**. For the Swagger Petstore API, a new folder named `swagger-petstore-v4` would be created. If the change is not breaking, a new folder should be created in `/apim_templates/apis` that corresponds to the next available **revision** for the version that the spec targets. For the Swagger Petstore API, if the spec referred to a revision to `v3` of the API, a new folder named `swagger-petstore-v3;rev=2` would be created. A subsequent revision would result in a new folder named `swagger-petstore-v3;rev=3`.
+
+API Ops expects each API folder to contain the following files:
+
+- `apiInformation.json`, which contains the API configuration data
+- `policy.xml`, which contains the API Policy applied to all API Operations
+- `specification.yaml`, which contains the Open API Spec for the API
+
+The `specification.yaml` file for a new version or revision will be the spec that is released by the backend API team. The `apiInformation.json` and `policy.xml` files from the previous versions or revisions should be used as templates to build the `apiInformation.json` and `policy.xml` files necessary for the newly created `/apim_templates/apis` folder. Generally, a new version's `apiInformation.json` will be nearly identical to the previous version's `apiInformation.json` file, with the `apiVersion` property updated. Similarly, a new revision's `apiInformation.json` will be nearly identical to the previous revision's `apiInformation.json` file, with the `apiRevision`, `apiRevisionDescription`, and `isCurrent` properties updated (only one revision may be current for each version). Additional properties may be updated, if necessary.
+
+In addition to the APIM API configuration itself, the API may need to be associated with existing Products. API Ops Products are stored in the `/apim_templates/products` folder, where each Product has it's own directory that corresponds to its name. API Ops uses a few files to define Product configuration, but uses the `/apim_templates/products/{PRODUCT_NAME}/apis.json` file to set the APIs the Product should be associated with. Each `apis.json` file contains an array of API names that correspond to the folders in `/apim_templates/apis`. The name of the newly created `/apim_templates/apis` folder should be added to `apis.json` for each of the Products the new API version/revision should be associated with.
+
+The `backends`, `diagnostics`, `loggers`, and `named values` folders in `/apim_templates` folder do not need to be updated on new spec changes. The url for the backend API does not change on spec updates and the monitoring configuration for the previous versions/revisions of the API will be applied to the new version/revision as well.
+
+In total, when a new version or revision is created, a new folder should be created in `/apim_templates/apis` that includes the following files:
+
+- `/apis/{API_NAME}/apiInformation.json`
+- `/apis/{API_NAME}/policy.xml`
+- `/apis/{API_NAME}/specification.yaml`
+
+And the `apis.json` file should be updated for each associated Product:
+
+- `/products/{PRODUCT_NAME}/apis.json`
+
+Once the new folder and files are added and updated, the new configuration can be published to API Management.
diff --git a/docs/testing.md b/docs/testing.md
@@ -0,0 +1,18 @@
+# Testing your API from Visual Studio Code
+
+The DevContainer will install two tools that will you help you test your APIs all from your IDE.
+ - [Azure API Management Extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-apimanagement)
+ - [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client)
+
+1. Use the APIM extension to Copy APIM Subscription Key by right clicking on the APIM instance
+
+![Copy Subscription Key](../assets/GetSubscriptionKey.png)
+
+2. Copy this value into the [Settings](../.vscode/settings.json) in the correct environment.
+
+3. Navigate to the API and "Test Operation" and it will generate you a REST file.
+![Test Operation](../assets/TestOperation.png)
+
+4. When you have the editor open with a .http file you will be able to chose which `environment` in the bottom corner of VSCode. This will make sure you subscription key is used when you make a request to APIM ![Chose Environment](../assets/ChoseEnvironment.png)
+
+Happy Testing!