Skip to content

Admin API Guidance

Jump to bottom
bganapa edited this page Sep 30, 2021 · 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

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

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