Skip to content

Commit 00498e6

Browse files
v-regandownerv-regandowner
authored
Merge pull request #280708 from waldekmastykarz/apic-devproxy
Adds the discover shadow APIs tutorial
2 parents ce932b6 + 050037b commit 00498e6

File tree

6 files changed

+308
-0
lines changed

6 files changed

+308
-0
lines changed

‎articles/api-center/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,8 @@
3232
href: register-apis.md
3333
- name: 3 - Add environments and deployments
3434
href: configure-environments-deployments.md
35+
- name: 4 - Discover shadow APIs
36+
href: discover-shadow-apis-dev-proxy.md
3537
- name: API inventory
3638
items:
3739
- name: Manage inventory - Azure CLI

‎articles/api-center/discover-shadow-apis-dev-proxy.md

Lines changed: 306 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,306 @@
1+
---
2+
title: Tutorial - Discover shadow APIs using Dev Proxy
3+
description: In this tutorial, you learn how to discover shadow APIs in your apps using Dev Proxy and onboard them to API Center.
4+
author: waldekmastykarz
5+
ms.service: api-center
6+
ms.topic: tutorial
7+
ms.date: 07/12/2024
8+
ms.author: wmastyka
9+
---
10+
11+
# Tutorial - Discover shadow APIs using Dev Proxy
12+
13+
Using Azure API Center you catalog APIs used in your organization. This allows you to tell which APIs you use, where the API is in its lifecycle, and who to contact if there are issues. In short, having an up-to-date catalog of APIs helps you improve the governance-, compliance-, and security posture.
14+
15+
When building your app, especially if you're integrating new scenarios, you might be using APIs that aren't registered in Azure API Center. These APIs are called shadow APIs. Shadow APIs are APIs that aren't registered in your organization. They might be APIs that aren't yet registered, or they might be APIs that aren't meant to be used in your organization.
16+
17+
One way to check for shadow APIs is by using [Dev Proxy](https://aka.ms/devproxy). Dev Proxy is an API simulator that intercepts and analyzes API requests from applications. One feature of Dev Proxy is checking if the intercepted API requests belong to APIs registered in API Center.
18+
19+
:::image type="content" source="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-plugin.png" alt-text="Screenshot of a command prompt showing Dev Proxy checking if the recorded API requests are registered in Azure API Center." lightbox="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-plugin.png":::
20+
21+
## Before you start
22+
23+
To detect shadow APIs, you need to have an [Azure API Center](/azure/api-center/) instance with information about the APIs that you use in your organization.
24+
25+
### Copy API Center information
26+
27+
From the Azure API Center instance Overview page, copy the **name** of the API Center instance, the name of the **resource group** and the **subscription ID**. You need this information to configure the Dev Proxy `ApiCenterOnboardingPlugin` so that it can connect to your Azure API Center instance.
28+
29+
:::image type="content" source="./media/discover-shadow-apis-dev-proxy/api-center-overview.png" alt-text="Screenshot of Azure API Center overview page with several properties highlighted." lightbox="./media/discover-shadow-apis-dev-proxy/api-center-overview.png":::
30+
31+
## Configure Dev Proxy
32+
33+
To check if your app is using shadow APIs, you need to enable the `ApiCenterOnboardingPlugin` in the Dev Proxy configuration file. To create a report of APIs that your app uses, add a reporter.
34+
35+
### Enable the `ApiCenterOnboardingPlugin`
36+
37+
In the `devproxyrc.json` file, add the following configuration:
38+
39+
```json
40+
{
41+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
42+
"plugins": [
43+
{
44+
"name": "ApiCenterOnboardingPlugin",
45+
"enabled": true,
46+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
47+
"configSection": "apiCenterOnboardingPlugin"
48+
}
49+
],
50+
"urlsToWatch": [
51+
"https://jsonplaceholder.typicode.com/*"
52+
],
53+
"apiCenterOnboardingPlugin": {
54+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
55+
"resourceGroupName": "demo",
56+
"serviceName": "contoso-api-center",
57+
"workspaceName": "default",
58+
"createApicEntryForNewApis": false
59+
}
60+
}
61+
```
62+
63+
In the `subscriptionId`, `resourceGroupName`, and `serviceName` properties, provide the information about your Azure API Center instance.
64+
65+
In the `urlsToWatch` property, specify the URLs that your app uses.
66+
67+
> [!TIP]
68+
> Use the [Dev Proxy Toolkit](https://aka.ms/devproxy/toolkit) Visual Studio Code extension to easily manage Dev Proxy configuration.
69+
70+
### Add a reporter
71+
72+
The `ApiCenterOnboardingPlugin` produces a report of APIs that your app is using. To view this report, add a reporter to your Dev Proxy configuration file. Dev Proxy offers several [reporters](/microsoft-cloud/dev/dev-proxy/technical-reference/overview#reporters). In this example, you use the [plain-text reporter](/microsoft-cloud/dev/dev-proxy/technical-reference/plaintextreporter).
73+
74+
Update your `devproxyrc.json` file with a reference to the plain-text reporter:
75+
76+
```json
77+
{
78+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
79+
"plugins": [
80+
{
81+
"name": "ApiCenterOnboardingPlugin",
82+
"enabled": true,
83+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
84+
"configSection": "apiCenterOnboardingPlugin"
85+
},
86+
{
87+
"name": "PlainTextReporter",
88+
"enabled": true,
89+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
90+
}
91+
],
92+
"urlsToWatch": [
93+
"https://jsonplaceholder.typicode.com/*"
94+
],
95+
"apiCenterOnboardingPlugin": {
96+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
97+
"resourceGroupName": "demo",
98+
"serviceName": "contoso-api-center",
99+
"workspaceName": "default",
100+
"createApicEntryForNewApis": false
101+
}
102+
}
103+
```
104+
105+
## Check if your app is using shadow APIs
106+
107+
To check if your app is using shadow APIs, connect to your Azure subscription, run Dev Proxy, and let it intercept API requests from your app. Dev Proxy then compares the information about the API requests with the information from Azure API Center and reports on any APIs that aren't registered in API Center.
108+
109+
### Connect to your Azure subscription
110+
111+
Dev Proxy uses information from Azure API Center to determine if your app is using shadow APIs. To get this information, it needs a connection to your Azure subscription. You can connect to your Azure subscription in [several ways](/microsoft-cloud/dev/dev-proxy/technical-reference/apicenterproductionversionplugin#remarks).
112+
113+
### Run Dev Proxy
114+
115+
After connecting to your Azure subscription, start Dev Proxy. If you start Dev Proxy from the same folder where your `devproxyrc.json` file is located, it automatically loads the configuration. Otherwise, specify the path to the configuration file using the `--config-file` option.
116+
117+
When Dev Proxy starts, it checks that it can connect to your Azure subscription. When the connection is successful, you see a message similar to:
118+
119+
```text
120+
info Plugin ApiCenterOnboardingPlugin connecting to Azure...
121+
info Listening on 127.0.0.1:8000...
122+
123+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
124+
Press CTRL+C to stop Dev Proxy
125+
```
126+
127+
Press <kbd>r</kbd> to start recording API requests from your app.
128+
129+
### Use your app
130+
131+
Use your app as you would normally do. Dev Proxy intercepts the API requests and stores information about them in memory. In the command line where Dev Proxy runs, you should see information about API requests that your app makes.
132+
133+
```text
134+
info Plugin ApiCenterOnboardingPlugin connecting to Azure...
135+
info Listening on 127.0.0.1:8000...
136+
137+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
138+
Press CTRL+C to stop Dev Proxy
139+
140+
◉ Recording...
141+
142+
req ╭ GET https://jsonplaceholder.typicode.com/posts
143+
api ╰ Passed through
144+
145+
req ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
146+
api ╰ Passed through
147+
```
148+
149+
### Check shadow APIs
150+
151+
Stop the recording by pressing <kbd>s</kbd>. Dev Proxy connects to the API Center instance and compares the information about requests with the information from API Center.
152+
153+
```text
154+
info Plugin ApiCenterOnboardingPlugin connecting to Azure...
155+
info Listening on 127.0.0.1:8000...
156+
157+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
158+
Press CTRL+C to stop Dev Proxy
159+
160+
◉ Recording...
161+
162+
req ╭ GET https://jsonplaceholder.typicode.com/posts
163+
api ╰ Passed through
164+
165+
req ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
166+
api ╰ Passed through
167+
○ Stopped recording
168+
info Checking if recorded API requests belong to APIs in API Center...
169+
info Loading APIs from API Center...
170+
info Loading API definitions from API Center...
171+
```
172+
173+
When Dev Proxy finishes its analysis, it creates a report in a file named `ApiCenterOnboardingPlugin_PlainTextReporter.txt` with the following contents:
174+
175+
```text
176+
New APIs that aren't registered in Azure API Center:
177+
178+
https://jsonplaceholder.typicode.com:
179+
DELETE https://jsonplaceholder.typicode.com/posts/1
180+
181+
APIs that are already registered in Azure API Center:
182+
183+
GET https://jsonplaceholder.typicode.com/posts
184+
```
185+
186+
### Automatically onboard shadow APIs
187+
188+
The `ApiCenterOnboardingPlugin` can not only detect shadow APIs, but also automatically onboard them to API Center. To automatically onboard shadow APIs, in the Dev Proxy configuration file, update the `createApicEntryForNewApis` to `true`.
189+
190+
```json
191+
{
192+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
193+
"plugins": [
194+
{
195+
"name": "ApiCenterOnboardingPlugin",
196+
"enabled": true,
197+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
198+
"configSection": "apiCenterOnboardingPlugin"
199+
},
200+
{
201+
"name": "PlainTextReporter",
202+
"enabled": true,
203+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
204+
}
205+
],
206+
"urlsToWatch": [
207+
"https://jsonplaceholder.typicode.com/*"
208+
],
209+
"apiCenterOnboardingPlugin": {
210+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
211+
"resourceGroupName": "demo",
212+
"serviceName": "contoso-api-center",
213+
"workspaceName": "default",
214+
"createApicEntryForNewApis": true
215+
}
216+
}
217+
```
218+
219+
When you run Dev Proxy with `createApicEntryForNewApis` set to `true`, it automatically creates new API entries in Azure API Center for the shadow APIs that it detects.
220+
221+
:::image type="content" source="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api.png" alt-text="Screenshot of API Center showing a newly onboarded API." lightbox="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api.png":::
222+
223+
### Automatically onboard shadow APIs with OpenAPI spec
224+
225+
When you choose to automatically onboard, shadow APIs to API Center, you can have Dev Proxy generate the OpenAPI spec for the API. Onboarding APIs with OpenAPI specs speeds up onboarding of missing endpoints and provide you with the necessary information about the API. When the `ApiCenterOnboardingPlugin` detects, that Dev Proxy created a new OpenAPI spec, it associates it with the corresponding onboarded API in API Center.
226+
227+
To automatically generate OpenAPI specs for onboarded APIs, update Dev Proxy configuration to include the [`OpenApiSpecGeneratorPlugin`](/microsoft-cloud/dev/dev-proxy/technical-reference/openapispecgeneratorplugin).
228+
229+
```json
230+
{
231+
"$schema": "https://raw.githubusercontent.com/microsoft/dev-proxy/main/schemas/v0.19.0/rc.schema.json",
232+
"plugins": [
233+
{
234+
"name": "OpenApiSpecGeneratorPlugin",
235+
"enabled": true,
236+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
237+
},
238+
{
239+
"name": "ApiCenterOnboardingPlugin",
240+
"enabled": true,
241+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll",
242+
"configSection": "apiCenterOnboardingPlugin"
243+
},
244+
{
245+
"name": "PlainTextReporter",
246+
"enabled": true,
247+
"pluginPath": "~appFolder/plugins/dev-proxy-plugins.dll"
248+
}
249+
],
250+
"urlsToWatch": [
251+
"https://jsonplaceholder.typicode.com/*"
252+
],
253+
"apiCenterOnboardingPlugin": {
254+
"subscriptionId": "00000000-0000-0000-0000-000000000000",
255+
"resourceGroupName": "demo",
256+
"serviceName": "contoso-api-center",
257+
"workspaceName": "default",
258+
"createApicEntryForNewApis": true
259+
}
260+
}
261+
```
262+
263+
> [!IMPORTANT]
264+
> Dev Proxy executes plugins in the order they're registered in the configuration. You need to register the `OpenApiSpecGeneratorPlugin` first so that it can create OpenAPI specs before the `ApiCenterOnboardingPlugin` onboards new APIs.
265+
266+
When you run Dev Proxy with this configuration, it automatically creates new API entries in Azure API Center for the shadow APIs that it detects. For each new API, Dev Proxy generates an OpenAPI spec and associates it with the corresponding onboarded API in API Center.
267+
268+
```text
269+
info Plugin ApiCenterOnboardingPlugin connecting to Azure...
270+
info Listening on 127.0.0.1:8000...
271+
272+
Hotkeys: issue (w)eb request, (r)ecord, (s)top recording, (c)lear screen
273+
Press CTRL+C to stop Dev Proxy
274+
275+
◉ Recording...
276+
277+
req ╭ GET https://jsonplaceholder.typicode.com/posts
278+
api ╰ Passed through
279+
280+
req ╭ DELETE https://jsonplaceholder.typicode.com/posts/1
281+
api ╰ Passed through
282+
○ Stopped recording
283+
info Creating OpenAPI spec from recorded requests...
284+
info Created OpenAPI spec file jsonplaceholder.typicode.com-20240614104931.json
285+
info Checking if recorded API requests belong to APIs in API Center...
286+
info Loading APIs from API Center...
287+
info Loading API definitions from API Center...
288+
info New APIs that aren't registered in Azure API Center:
289+
290+
https://jsonplaceholder.typicode.com:
291+
DELETE https://jsonplaceholder.typicode.com/posts/1
292+
info Creating new API entries in API Center...
293+
info Creating API new-jsonplaceholder-typicode-com-1718354977 for https://jsonplaceholder.typicode.com...
294+
info DONE
295+
```
296+
297+
:::image type="content" source="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api-openapi-spec.png" alt-text="Screenshot of Azure API Center showing a newly onboarded API with an OpenAPI spec." lightbox="./media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api-openapi-spec.png":::
298+
299+
## Summary
300+
301+
Using Dev Proxy and its `ApiCenterOnboardingPlugin`, you can check if your app is using shadow APIs. The plugin analyzes API requests from your app and reports on any API requests that aren't registered in Azure API Center. The plugin allows you to easily onboard missing APIs to API Center. By combining the `ApiCenterOnboardingPlugin` plugin with the `OpenApiSpecGeneratorPlugin`, you can automatically generate OpenAPI specs for the newly onboarded APIs. You can run this check manually or integrate with your CI/CD pipeline to ensure that your app is using registered APIs before releasing it to production.
302+
303+
## More information
304+
305+
- [Learn more about Dev Proxy](/microsoft-cloud/dev/dev-proxy/overview)
306+
- [Learn more about Azure API Center](./key-concepts.md)

‎articles/api-center/media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api-openapi-spec.png

209 KB
Loading

‎articles/api-center/media/discover-shadow-apis-dev-proxy/api-center-onboarding-new-api.png

139 KB
Loading

‎articles/api-center/media/discover-shadow-apis-dev-proxy/api-center-onboarding-plugin.png

197 KB
Loading

‎articles/api-center/media/discover-shadow-apis-dev-proxy/api-center-overview.png

155 KB
Loading

0 commit comments

Comments
 (0)