Use metadata for API governance
This article provides background about metadata and how to use it for API governance in Azure API Center. You define and set metadata to organize and filter APIs and other entities in your API center. Metadata can be built in or custom, and you can develop a metadata schema to enforce consistency across your APIs, environments, and deployments.
Built-in metadata
When creating or updating APIs, environments, and deployments in your API center, you set certain built-in metadata properties, such as the API type (REST, WSDL, and so on).
The following tables list built-in metadata provided for Azure API Center entities. For details, see the API Center REST API reference. Tables don't include standard Azure properties such as resource identifiers, display titles, and descriptions. Not all properties are required.
APIs
| Metadata | Description | Example values |
|---|---|---|
| kind | kind (type) of API | REST, SOAP, GraphQL |
| lifecycle stage | stage of the API development lifecycle | design, development |
| license | license information for the API | SPDX identifier, link to license text |
| external documentation | site for external documentation for the API | URL pointing to documentation |
| contact information | points of contact for the API | email address, name, URL |
| terms of service | terms of service for the API | URL pointing to terms of service |
Environments
| Metadata | Description | Example values |
|---|---|---|
| kind | kind (type) of environment | production, staging, development |
| server | server information of the environment | type and URL pointing to the environment server |
| server type | type of environment server | API Management server, Kubernetes server, Apigee server |
| onboarding | onboarding information for the environment | instructions and URL pointing to environment's developer portal |
Deployments
| Metadata | Description | Example values |
|---|---|---|
| server | server information of the deployment | URL pointing to the deployment server |
| state | state of the deployment | active, inactive |
Custom metadata
Define custom metadata using the Azure portal, the Azure API Center REST API, or the Azure CLI to help organize and filter APIs, environments, and deployments in your API center. Azure API Center supports custom metadata of the following types.
| Type | Description | Example name |
|---|---|---|
| boolean | true or false | IsInternal |
| number | numeric value | YearOfCreation |
| string | text value | GitHubRepository |
| array | list of values | Tags |
| built-in choice | built-in list of choices | Department |
| object | complex object composed of multiple types | APIApprover |
Important
Don't include any sensitive, confidential, or personal information in the titles (names) of metadata you define. These titles are visible in monitoring logs that are used by Microsoft to improve the functionality of the service. However, other metadata details and values are your protected customer data.
Assign metadata to entities
Custom metadata properties can be assigned to APIs, environments, or deployments in your API center. For example, define and assign Department metadata to APIs, so that when an API is registered or a new API version is added, the department responsible for the API is specified.
If assigned to an entity, metadata is either optional or required. For example, you might require that the Department metadata is set only for APIs, but allow YearOfCreation to be optional metadata for environments.
Note
- Define custom metadata at any time and apply to APIs and other entities in your API center.
- After defining custom metadata, you can change its assignment to an entity, for example from required to optional for APIs.
- You can change metadata values, but you can't delete or change the type of custom metadata that is currently set in APIs, environments, and deployments. Unassign the custom metadata from the entities first, and then you can delete or change them.
Use metadata for governance
Use built-in and custom metadata to organize your APIs, environments, and deployments in your API center. For example:
Enforce governance standards in your organization by requiring certain metadata to be set for APIs, environments, and deployments.
Search and filter APIs in your API center by metadata values. You can filter directly on the APIs page in the Azure portal, or use the Azure API Center REST API or Azure CLI to query APIs based on values of certain metadata.
