Skip to content

Commit 97e8111

Browse files
ttorblettorble
authored
Merge pull request #268197 from dlepow/apiceg
[API Center] Event Grid schema reference
2 parents 2bbb427 + 139d8f6 commit 97e8111

File tree

3 files changed

+175
-0
lines changed

3 files changed

+175
-0
lines changed

‎articles/api-center/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,5 +53,7 @@
5353
href: /java/api/overview/azure/apicenter
5454
- name: Python
5555
href: https://pypi.org/project/azure-mgmt-apicenter
56+
- name: Event Grid schema
57+
href: ../event-grid/event-schema-api-center.md
5658
- name: Resource Manager template
5759
href: /azure/templates/microsoft.apicenter/allversions

‎articles/event-grid/event-schema-api-center.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: Azure API Center as Event Grid source
3+
description: Describes the properties that are provided for Azure API Center events with Azure Event Grid
4+
ms.topic: conceptual
5+
ms.date: 03/05/2024
6+
author: dlepow
7+
ms.author: danlep
8+
---
9+
10+
# Azure API Center as an Event Grid source
11+
12+
This article provides the properties and schema for Azure API Center events. For an introduction to event schemas, see [Azure Event Grid event schema](event-schema.md).
13+
14+
## Available event types
15+
These events are triggered when a client adds or updates an API definition.
16+
17+
|Event name |Description|
18+
|----------|-----------|
19+
|**Microsoft.ApiCenter.ApiDefinitionAdded** |Triggered when an API definition is added in an API center. |
20+
|**Microsoft.ApiCenter.ApiDefinitionUpdated** |Triggered when an API definition is updated in an API center.|
21+
22+
## Example event
23+
When an event is triggered, the API Center service sends data about that event to subscribing endpoint. This section contains an example of what that data would look like for each API Center event.
24+
25+
26+
# [Cloud event schema](#tab/cloud-event-schema)
27+
28+
29+
### Microsoft.ApiCenter.ApiDefinitionAdded event
30+
31+
```json
32+
[{
33+
"source": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services",
34+
"subject": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services/{api_center_name}/workspaces/default/apis/{api_name}/versions/{version_name}/definitions/{definition_name}",
35+
"type": "Microsoft.ApiCenter.ApiDefinitionAdded",
36+
"time": "2024-03-01T00:00:00.0000000Z",
37+
"id": "00000000-0000-0000-0000-000000000000",
38+
"data": {
39+
"title": "OpenAPI",
40+
"description": "Default spec",
41+
"specification": {
42+
"name": "openapi",
43+
"version": "3.0.1"
44+
}
45+
},
46+
"specversion": "1.0"
47+
}]
48+
```
49+
50+
### Microsoft.ApiCenter.ApiDefinitionUpdated event
51+
52+
```json
53+
[{
54+
"source": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services",
55+
"subject": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services/{api_center_name}/workspaces/default/apis/{api_name}/versions/{version_name}/definitions/{definition_name}",
56+
"type": "Microsoft.ApiCenter.ApiDefinitionUpdated",
57+
"time": "2024-03-01T00:00:00.0000000Z",
58+
"id": "00000000-0000-0000-0000-000000000000",
59+
"data": {
60+
"title": "OpenAPI",
61+
"description": "Default spec",
62+
"specification": {
63+
"name": "openapi",
64+
"version": "3.0.1"
65+
}
66+
},
67+
"specversion": "1.0"
68+
}]
69+
```
70+
71+
72+
# [Event Grid event schema](#tab/event-grid-event-schema)
73+
74+
### Microsoft.ApiCenter.ApiDefinitionAdded event
75+
76+
```json
77+
[{
78+
"topic": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services",
79+
"subject": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services/{api_center_name}/workspaces/default/apis/{api_name}/versions/{version_name}/definitions/{definition_name}",
80+
"eventType": "Microsoft.ApiCenter.ApiDefinitionAdded",
81+
"id": "00000000-0000-0000-0000-000000000000",
82+
"data": {
83+
"title": "OpenAPI",
84+
"description": "Default spec",
85+
"specification": {
86+
"name": "openapi",
87+
"version": "3.0.1"
88+
}
89+
},
90+
"dataVersion": "1.0.0",
91+
"metadataVersion": "1",
92+
"eventTime": "2024-03-01T00:00:00.0000000Z"
93+
}]
94+
```
95+
96+
### Microsoft.ApiCenter.ApiDefinitionUpdated event
97+
98+
```json
99+
[{
100+
"topic": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services",
101+
"subject": "/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/providers/Microsoft.ApiCenter/services/{api_center_name}/workspaces/default/apis/{api_name}/versions/{version_name}/definitions/{definition_name}",
102+
"eventType": "Microsoft.ApiCenter.ApiDefinitionUpdated",
103+
"id": "00000000-0000-0000-0000-000000000000",
104+
"data": {
105+
"title": "OpenAPI",
106+
"description": "Default spec",
107+
"specification": {
108+
"name": "openapi",
109+
"version": "3.0.1"
110+
}
111+
},
112+
"dataVersion": "1.0.0",
113+
"metadataVersion": "1",
114+
"eventTime": "2024-03-01T00:00:00.0000000Z"
115+
}]
116+
```
117+
118+
---
119+
120+
## Event properties
121+
122+
# [Cloud event schema](#tab/cloud-event-schema)
123+
124+
An event has the following top-level data:
125+
126+
| Property | Type | Description |
127+
| -------- | ---- | ----------- |
128+
| `source` | string | Full resource path to the event source. This field isn't writeable. Event Grid provides this value. |
129+
| `subject` | string | Publisher-defined path to the event subject. |
130+
| `type` | string | One of the registered event types for this event source. |
131+
| `time` | string | The time the event is generated based on the provider's UTC time. |
132+
| `id` | string | Unique identifier for the event. |
133+
| `data` | object | Azure API Center event data. |
134+
| `specversion` | string | CloudEvents schema specification version. |
135+
136+
# [Event Grid event schema](#tab/event-grid-event-schema)
137+
138+
An event has the following top-level data:
139+
140+
| Property | Type | Description |
141+
| -------- | ---- | ----------- |
142+
| `topic` | string | Full resource path to the event source. This field isn't writeable. Event Grid provides this value. |
143+
| `subject` | string | Publisher-defined path to the event subject. |
144+
| `eventType` | string | One of the registered event types for this event source. |
145+
| `id` | string | Unique identifier for the event. |
146+
| `data` | object | Azure API Center event data. |
147+
| `dataVersion` | string | The schema version of the data object. The publisher defines the schema version. |
148+
| `metadataVersion` | string | The schema version of the event metadata. Event Grid defines the schema of the top-level properties. Event Grid provides this value. |
149+
| `eventTime` | string | The time the event is generated based on the provider's UTC time. |
150+
151+
---
152+
153+
The data object has the following properties:
154+
155+
| Property | Type | Description |
156+
| -------- | ---- | ----------- |
157+
| `title` | string | The title of the API definition. |
158+
| `description` | string | The description of the API definition. |
159+
| `specification` | string | The API specification properties, consisting of `name` (specification name) and `version` (specification version) |
160+
161+
## Tutorials and how-tos
162+
163+
|Title |Description |
164+
|---------|---------|
165+
| [Enable linting and analysis for API governance in your API center](https://aka.ms/apicenter/docs/linting)| Use Event Grid events to trigger linting to analyze API definitions in your API center. |
166+
167+
## Related content
168+
169+
* For an introduction to Azure Event Grid, see [What is Event Grid?](overview.md)
170+
* For more information about creating an Azure Event Grid subscription, see [Event Grid subscription schema](subscription-creation-schema.md).
171+

‎articles/event-grid/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,6 +319,8 @@ items:
319319
href: system-topics.md
320320
- name: Event sources (publishers)
321321
items:
322+
- name: Azure API Center
323+
href: event-schema-api-center.md
322324
- name: Azure API Management
323325
href: event-schema-api-management.md
324326
- name: Azure App Configuration

0 commit comments

Comments
 (0)