Skip to content

Commit a7ef024

Browse files
v-dirichardsv-dirichards
authored
Merge pull request #257016 from dlepow/apiccon
[API Center] Conceptual updates
2 parents b60d1c6 + 37d3e1b commit a7ef024

19 files changed

+459
-280
lines changed

‎articles/api-center/TOC.yml

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,32 @@
11
- name: Azure API Center Documentation
22
href: index.yml
3-
- name: Overview
3+
- name: Get started
44
expanded: true
55
items:
6+
- name: Overview
7+
items:
68
- name: What is API Center?
79
displayName: Overview
810
href: overview.md
11+
- name: Key concepts
12+
href: key-concepts.md
913
- name: Service limits
1014
href: ../azure-resource-manager/management/azure-subscription-service-limits.md#api-center-preview-limits
11-
- name: Concepts
12-
items:
13-
- name: Key concepts
14-
href: key-concepts.md
15-
- name: Tutorials
16-
items:
17-
- name: Set up an API center
18-
href: set-up-api-center.md
15+
- name: Quickstarts
16+
items:
17+
- name: Create an API center
18+
href: set-up-api-center.md
19+
- name: Tutorials
20+
items:
21+
- name: 1 - Customize metadata properties
22+
href: add-metadata-properties.md
23+
- name: 2 - Add APIs to the inventory
24+
href: register-apis.md
25+
- name: 3 - Add environments and deployments
26+
href: configure-environments-deployments.md
27+
#- name: API inventory
28+
#- name: API governance
29+
#- name: API discovery and consumption
1930
- name: Reference
2031
items:
2132
- name: REST API

‎articles/api-center/add-metadata-properties.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Tutorial - Customize metadata properties in Azure API Center (preview) | Microsoft Docs
3+
description: In this tutorial, define custom metadata properties in your API center. Use custom and built-in properties to organize your APIs.
4+
author: dlepow
5+
ms.service: api-center
6+
ms.topic: tutorial
7+
ms.date: 11/07/2023
8+
ms.author: danlep
9+
ms.custom:
10+
---
11+
12+
# Tutorial: Customize metadata properties
13+
14+
In this tutorial, define custom properties to help you organize your APIs and other information in your API center. Use custom metadata properties and several built-in properties for search and filtering and to enforce governance standards in your organization.
15+
16+
For background information about the metadata schema in API Center, see [Key concepts](key-concepts.md).
17+
18+
In this tutorial, you learn how to use the portal to:
19+
> [!div class="checklist"]
20+
> * Define custom metadata properties in your API center
21+
> * View the metadata schema
22+
23+
[!INCLUDE [api-center-preview-feedback](includes/api-center-preview-feedback.md)]
24+
25+
## Prerequisites
26+
27+
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
28+
29+
## Define properties in the metadata schema
30+
31+
You organize your API inventory by setting values of metadata properties. While several common properties such as "API type" and "Version lifecycle" are available out of the box, each API center provides a configurable metadata schema so you can add properties that are specific to your organization.
32+
33+
Here you define two example properties: *Line of business* and *Public-facing*; if you prefer, define other properties of your own. When you add or update APIs and other information in your inventory, you'll set values for these properties and any common built-in properties.
34+
35+
> [!IMPORTANT]
36+
> Take care not to include any sensitive, confidential, or personal information in the titles (names) of metadata properties 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.
37+
38+
1. In the left menu, select **Metadata schema > + Add property**.
39+
40+
1. On the **Details** tab, enter information about the property.
41+
42+
1. In **Title**, enter *Line of business*.
43+
44+
1. Select type **Predefined choices** and enter choices such as *Marketing, Finance, IT, Sales*, and so on. Optionally enable **Allow selection of multiple values**.
45+
46+
:::image type="content" source="media/add-metadata-properties/metadata-property-details.png" alt-text="Screenshot of metadata schema property in the portal.":::
47+
48+
1. On the **Assignments** tab, select **Required** for APIs. Select **Optional** for Deployments and Environments. (You'll add these entities in later tutorials.)
49+
50+
:::image type="content" source="media/add-metadata-properties/metadata-property-assignments.png" alt-text="Screenshot of metadata property assignments in the portal.":::
51+
52+
1. On the **Review + Create** tab, review the settings and select **Create**.
53+
54+
The property is added to the list.
55+
56+
1. Select **+ Add property** to add another property.
57+
58+
1. On the **Details** tab, enter information about the property.
59+
60+
1. In **Title**, enter *Public-facing*.
61+
62+
1. Select type **Boolean**.
63+
64+
1. On the **Assignments** tab, select **Required** for APIs. Select **Not applicable** for Deployments and Environments.
65+
66+
1. On the **Review + Create** tab, review the settings and select **Create**.
67+
68+
The property is added to the list.
69+
70+
## View metadata schema
71+
72+
You can view and download the JSON schema for the metadata properties in your API center. The schema includes built-in and custom properties.
73+
74+
1. In the left menu, select **Metadata schema > View schema**.
75+
76+
1. Select **View schema > API** to see the metadata schema for APIs, which includes built-in properties and the properties that you added. You can also view the metadata schema defined for deployments and environments in your API center.
77+
78+
:::image type="content" source="media/add-metadata-properties/metadata-schema.png" alt-text="Screenshot of metadata schema in the portal." lightbox="media/add-metadata-properties/metadata-schema.png":::
79+
80+
> [!NOTE]
81+
> * Add properties in the schema at any time and apply them to APIs and other entities in your API center.
82+
> * After adding a property, you can change its assignment to an entity, for example from required to optional for APIs.
83+
> * You can't delete, unassign, or change the type of properties that are currently set in entities. Remove them from the entities first, and then you can delete or change them.
84+
85+
## Next steps
86+
87+
In this tutorial, you learned how to use the portal to:
88+
> [!div class="checklist"]
89+
> * Define custom metadata properties in your API center
90+
> * View the metadata schema
91+
92+
Now that you've prepared your metadata schema, add APIs to the inventory in your API center.
93+
94+
> [!div class="nextstepaction"]
95+
> [Register APIs in your API inventory](register-apis.md)
96+

‎articles/api-center/configure-environments-deployments.md

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Tutorial - Add environments and deployments in Azure API Center (preview) | Microsoft Docs
3+
description: In this tutorial, augment the API inventory in your API center by adding information about API environments and deployments.
4+
author: dlepow
5+
ms.service: api-center
6+
ms.topic: tutorial
7+
ms.date: 11/07/2023
8+
ms.author: danlep
9+
ms.custom:
10+
---
11+
12+
13+
14+
# Tutorial: Add environments and deployments in your API inventory
15+
16+
Augment the inventory in your API center by adding information about API environments and deployments.
17+
18+
* An *environment* represents a location where an API runtime could be deployed, for example, an API management platform.
19+
20+
* A *deployment* is a location (an address) where users can access an API.
21+
22+
For background information about APIs, deployments, and other entities that you can inventory in API Center, see [Key concepts](key-concepts.md).
23+
24+
In this tutorial, you learn how to use the portal to:
25+
> [!div class="checklist"]
26+
> * Add information about API environments
27+
> * Add information about API deployments
28+
29+
[!INCLUDE [api-center-preview-feedback](includes/api-center-preview-feedback.md)]
30+
31+
32+
## Prerequisites
33+
34+
* An API center in your Azure subscription. If you haven't created one already, see [Quickstart: Create your API center](set-up-api-center.md).
35+
36+
* One or more APIs registered in your API center. If you haven't registered any APIs already, see [Tutorial: Register APIs in your API inventory](register-apis.md). This tutorial uses the sample APIs you added from the previous tutorial.
37+
38+
## Add an environment
39+
40+
Use your API center to keep track of your real-world API environments. For example, you might use Azure API Management or another solution to distribute, secure, and monitor some of your APIs. Or you might directly serve some APIs using a compute service or a Kubernetes cluster. You can add multiple environments to your API center, each aligned with a lifecycle stage such as development, testing, staging, or production.
41+
42+
Here you add information about a fictitious Azure API Management environment to your API center. If you prefer, add information about one of your existing environments. You'll configure both built-in properties and any custom metadata properties you defined in a [previous tutorial](add-metadata-properties.md).
43+
44+
1. In the portal, navigate to your API center.
45+
46+
1. In the left menu, select **Environments** > **+ Add environment**.
47+
48+
1. On the **Create environment** page, add the following information. If you previously defined the custom *Line of business* metadata property or other properties assigned to environments, you'll see them at the bottom of the page.
49+
50+
|Setting|Value|Description|
51+
|-------|-----|-----------|
52+
|**Title**| Enter *My Testing*.| Name you choose for the environment. |
53+
|**Identification**|After you enter the preceding title, API Center generates this identifier, which you can override.| Azure resource name for the environment.|
54+
|**Environment type**| Select **Testing** from the dropdown.| Type of environment for APIs.|
55+
| **Description** | Optionally enter a description. | Description of the environment. |
56+
| **Server** | | |
57+
|**Type**| Optionally select **Azure API Management** from the dropdown.|Type of API management solution used.|
58+
| **Management portal URL** | Optionally enter a URL such as `https://admin.contoso.com` | URL of management interface for environment. |
59+
| **Onboarding** | | |
60+
| **Development portal URL** | Optionally enter a URL such as `https://developer.contoso.com` | URL of interface for developer onboarding in the environment. |
61+
| **Instructions** | Optionally select **Edit** and enter onboarding instructions in standard Markdown. | Instructions to onboard to APIs from the environment. |
62+
| **Line of business** | If you added this custom property, optionally make a selection from the dropdown, such as **IT**. | Custom metadata property that identifies the business unit that manages APIs in the environment. |
63+
64+
:::image type="content" source="media/configure-environments-deployments/create-environment.png" alt-text="Screenshot of adding an API environment in the portal." :::
65+
66+
1. Select **Create**. The environment appears on the list of environments.
67+
68+
## Add a deployment
69+
70+
API center can also help you catalog your API deployments - the runtime environments where the APIs you track are deployed.
71+
72+
Here you add a deployment by associating one of your APIs with the environment you created in the previous section. You'll configure both built-in properties and any custom metadata properties you've defined.
73+
74+
1. In the portal, navigate to your API center.
75+
76+
1. In the left menu, select **APIs** and then select an API, for example, the *Demo Conference API*.
77+
78+
1. On the **Demo Conference API** page, select **Deployments** > **+ Add deployment**.
79+
80+
1. In the **Add deployment** page, add the following information. If you previously defined the custom *Line of business* metadata property or other properties assigned to environments, you'll see them at the bottom of the page.
81+
82+
|Setting|Value|Description|
83+
|-------|-----|-----------|
84+
|**Title**| Enter *v1 Deployment*.| Name you choose for the deployment. |
85+
|**Identification**|After you enter the preceding title, API Center generates this identifier, which you can override.| Azure resource name for the deployment.|
86+
| **Description** | Optionally enter a description. | Description of the deployment. |
87+
| **Environment** | Make a selection from the dropdown, such as *My Testing*, or optionally select **Create new**.| New or existing environment where the API version is deployed. |
88+
| **Definition** | Select or add a definition file for a version of the Demo Conference API. | API definition file. |
89+
| **Runtime URL** | Enter a base URL, for example, `https://api.contoso.com/conference`. | Base runtime URL for the API in the environment. |
90+
| **Line of business** | If you added this custom property, optionally make a selection from the dropdown, such as **IT**. | Custom metadata property that identifies the business unit that manages APIs in the environment. |
91+
92+
:::image type="content" source="media/configure-environments-deployments/add-deployment.png" alt-text="Screenshot of adding an API deployment in the portal." :::
93+
94+
1. Select **Create**. The deployment appears on the list of deployments.
95+
96+
In this tutorial, you learned how to use the portal to:
97+
> [!div class="checklist"]
98+
> * Add information about API environments
99+
> * Add information about API deployments
100+
101+
## Related content
102+
103+
* [Learn more about API Center](key-concepts.md)
104+

‎articles/api-center/index.yml

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,24 @@ landingContent:
2121
# Card
2222
- title: About API Center
2323
linkLists:
24-
- linkListType: overview
24+
- linkListType: get-started
2525
links:
2626
- text: What is API Center?
2727
url: overview.md
2828
- text: Key concepts
2929
url: key-concepts.md
30-
- linkListType: get-started
30+
# Card
31+
- title: Manage your API inventory
32+
linkLists:
33+
- linkListType: quickstart
3134
links:
32-
- text: Tutorial - Set up your API center
35+
- text: Create your API center
3336
url: set-up-api-center.md
37+
- linkListType: tutorial
38+
links:
39+
- text: 1 - Customize metadata properties
40+
url: add-metadata-properties.md
41+
- text: 2 - Add APIs to the inventory
42+
url: register-apis.md
43+
- text: 3 - Add environments and deployments
44+
url: configure-environments-deployments.md

0 commit comments

Comments
 (0)