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.

  

Related content

• What is Azure API Center?
• API Center - key concepts
• Tutorial: Define custom metadata