Skip to content

Admin API Guidance

Jump to bottom
Wei Shi edited this page Jun 1, 2023 · 11 revisions

Admin API Guidance

AzureStack Hub Admin APIs are only for Operators. These APIs are exposed only via Admin AzureStack Hub Resource Manager. For example 'List all the subscriptions in an AzureStack Hub Environment' is an admin API.

Developer flow

Here is a recommended flow for developing an Admin API

  • Author Open API Spec and make a Pull Request.
  • Notify azsdevexp alias for review.
  • The PR is automatically reviewed by azure ARM team and SDK team for compliance.
  • While the PR is in review, start developing the API. The PR could take more than a month to get it merged.
  • Start developing the Admin Powershell for the API from your fork. No need to wait until the Open API Spec PR is merged.
  • Once the spec changes are checked in to main branch of the specs repo, DeployBVT runs will identify an API Consistency bug as the product changes are not in the Deploy build yet. If this issue happens and the product changes are going to take time to get checked in, suggest adding APIConsistency exclusions to avoid the bug. For adding exclusions, pls follow the instructions (internal link)
  • Make a PR for azurestack-powershell repository with PR title prepended with "[<Azure Stack Hub release version>]", e.g. "[2301] Compute changes".
  • Before merging pull request, make sure you squashed and rebased your commits on latest dev branch so that you have one commit per pull request that is ready to merge without conflicts and without the unnecessary "merge branch '<branch 1 name>' into '<branch 2 name>'" commits.

Admin powershell is typically shipped within 2 weeks of the product update release.

Open API spec Authoring

Please look at the docs at the azure-rest-api-spec for guidance on authoring Open API Specs. When a new api version is created for the existing API, It is recommended to make two commits, one with the existing spec as such in the new folder and the second for the changes in the newer api version

Common Mistakes

  • Use the types from here for the common parameters like SubscriptionId, ApiVersionParameter, Resource, DefaultErrorResponse etc.

Open API spec Validation

CI validation explains all the tools run as part of the Pull Request and how those tools can be run locally.

The Open API spec review process is explained in the internal link here

Admin powershell generation

Please look at the docs here to get started on the powershell generation

FAQ

  1. How to author an ARM API?

Please refer to the ARM guidance here

  1. When does an API need a new api-version?

Any breaking changes needs a new api version. Please refer to the Breaking Change Policy for detailed instructions on what constitutes as a breaking change

  1. Do we need a new api version for adding a new API?

Adding an api to the existing api version is considered as a breaking change and we definitely need a newer api version. All customer environments are not getting the azure stack updates at the same time. Having a new API in the exsting api version will mislead the customer to try the new API in an older stamp which has not been updated. This is a breaking change. Azure Rest API specs team catches the breaking changes in the PR process itself and it will not get merged.

For any other queries, please reach out to azsdevexp alias or use the Teams channel

Clone this wiki locally