Skip to content

Commit 2d456cf

Browse files
cloudjumpercatlena-larionova
cloudjumpercat
and
lena-larionova
authored
feat(dev-portal): API packaging how to (#3580)
* Start drafting how to Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Rename how to and revise some of the steps for UI changes as well as making more specific Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply more step changes, draft-ish the validation step Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Add example spec, basic validate, fix some steps Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Minor phrasing cleanup Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * fix broken links * actually fix broken link * Apply PM feedback, backlinks Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com> * Update GW min version Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --------- Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> Co-authored-by: lena-larionova <54370747+lena-larionova@users.noreply.github.com>
1 parent 4e43fbf commit 2d456cf

File tree

9 files changed

+354
-33
lines changed

9 files changed

+354
-33
lines changed

‎app/_how-tos/automate-api-catalog-with-terraform.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ related_resources:
3636
url: /dev-portal/application-registration/
3737
- text: Application authentication strategies
3838
url: /dev-portal/auth-strategies/
39+
- text: Package APIs with Dev Portal
40+
url: /how-to/package-apis-with-dev-portal/
3941
prereqs:
4042
skip_product: true
4143
inline:

‎app/_how-tos/automate-api-catalog.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ related_resources:
5252
url: /dev-portal/application-registration/
5353
- text: Application authentication strategies
5454
url: /dev-portal/auth-strategies/
55+
- text: Package APIs with Dev Portal
56+
url: /how-to/package-apis-with-dev-portal/
5557
faqs:
5658
- q: I just edited or deleted my spec, document, page, or snippet. Why don't I immediately see these changes live in the Dev Portal?
5759
a: If you recently viewed the related content, your browser might be serving a cached version of the page. To fix this, you can clear your browser cache and refresh the page.

‎app/_how-tos/discover-and-govern-apis-with-service-catalog.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ related_resources:
2121
url: /catalog/integrations/
2222
- text: AWS API Gateway reference
2323
url: /catalog/integrations/aws-api-gateway/
24+
- text: Package APIs with Dev Portal
25+
url: /how-to/package-apis-with-dev-portal/
2426
automated_tests: false
2527
tldr:
2628
q: How do I discover and govern third-party APIs in {{site.konnect_short_name}}?

‎app/_how-tos/package-apis-with-dev-portal.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
title: "Package APIs with Dev Portal"
3+
description: "Learn how to compose existing APIs in Dev Portal into API packages."
4+
content_type: how_to
5+
related_resources:
6+
- text: About Dev Portal
7+
url: /dev-portal/
8+
- text: API packaging reference
9+
url: /catalog/api-packaging/
10+
automated_tests: false
11+
products:
12+
- dev-portal
13+
- gateway
14+
- catalog
15+
min_version:
16+
gateway: '3.13'
17+
works_on:
18+
- konnect
19+
tools:
20+
- deck
21+
tags:
22+
- api-catalog
23+
- api-composition
24+
25+
tldr:
26+
q: How do I create API packages from existing Dev Portal APIs?
27+
a: |
28+
Packaging APIs involves the following steps:
29+
1. Create an API and attach an OpenAPI spec.
30+
1. Apply the Access Control Enforcement (ACE) plugin globally on the control plane you want to link.
31+
1. Link a control plane to the API to allow developer consumption.
32+
1. Create an API package by adding operations and package rate limits.
33+
1. Publish the API package to Dev Portal.
34+
prereqs:
35+
inline:
36+
- title: "{{site.konnect_short_name}} roles"
37+
content: |
38+
To recover create API packages, you need the following [roles](/konnect-platform/teams-and-roles/):
39+
* Editor role for APIs
40+
* Publisher role for the API and API package
41+
* API Creator
42+
icon_url: /assets/icons/gateway.svg
43+
- title: Dev Portal
44+
include_content: prereqs/dev-portal-create-ui
45+
icon_url: /assets/icons/dev-portal.svg
46+
- title: Dev Portal APIs
47+
content: |
48+
To complete this guide, you'll need an API in Catalog:
49+
1. In the {{site.konnect_short_name}} sidebar, click **Catalog**.
50+
1. Click [**New API**](https://cloud.konghq.com/apis/create).
51+
1. In the **API name** field, enter `MyAPI`.
52+
1. Click **Create**.
53+
icon_url: /assets/icons/dev-portal.svg
54+
- title: Required entities
55+
content: |
56+
For this tutorial, you’ll need {{site.base_gateway}} entities, like Gateway Services and Routes, pre-configured. These entities are essential for {{site.base_gateway}} to function but installing them isn’t the focus of this guide.
57+
58+
1. Run the following command:
59+
60+
```yaml
61+
echo '
62+
_format_version: "3.0"
63+
services:
64+
- name: example-service
65+
url: http://httpbin.konghq.com/anything
66+
routes:
67+
- name: example-route
68+
paths:
69+
- "/anything"
70+
methods:
71+
- GET
72+
- PUT
73+
- POST
74+
- PATCH
75+
- DELETE
76+
service:
77+
name: example-service
78+
' | deck gateway apply -
79+
```
80+
81+
To learn more about entities, you can read our [entities documentation](/gateway/entities/).
82+
- title: API specification
83+
content: |
84+
To complete this guide, you'll need an API specification that matches the Route you created. {{site.konnect_catalog}} uses the spec to add operations to your API package.
85+
86+
```sh
87+
cat > example-api-spec.yaml << 'EOF'
88+
openapi: 3.0.0
89+
info:
90+
title: Example API
91+
description: Example API service for testing and documentation
92+
version: 1.0.0
93+
94+
servers:
95+
- url: http://httpbin.konghq.com
96+
description: Backend service (HTTP only, port 80)
97+
98+
paths:
99+
/anything:
100+
get:
101+
summary: Get anything
102+
description: Echo back GET request details
103+
operationId: getAnything
104+
tags:
105+
- Echo
106+
responses:
107+
'200':
108+
description: Successful response
109+
content:
110+
application/json:
111+
schema:
112+
$ref: '#/components/schemas/EchoResponse'
113+
'426':
114+
description: Upgrade Required (HTTPS redirect)
115+
116+
post:
117+
summary: Post anything
118+
description: Echo back POST request details
119+
operationId: postAnything
120+
tags:
121+
- Echo
122+
requestBody:
123+
content:
124+
application/json:
125+
schema:
126+
type: object
127+
additionalProperties: true
128+
responses:
129+
'200':
130+
description: Successful response
131+
content:
132+
application/json:
133+
schema:
134+
$ref: '#/components/schemas/EchoResponse'
135+
'426':
136+
description: Upgrade Required (HTTPS redirect)
137+
138+
put:
139+
summary: Put anything
140+
description: Echo back PUT request details
141+
operationId: putAnything
142+
tags:
143+
- Echo
144+
requestBody:
145+
content:
146+
application/json:
147+
schema:
148+
type: object
149+
additionalProperties: true
150+
responses:
151+
'200':
152+
description: Successful response
153+
content:
154+
application/json:
155+
schema:
156+
$ref: '#/components/schemas/EchoResponse'
157+
'426':
158+
description: Upgrade Required (HTTPS redirect)
159+
160+
patch:
161+
summary: Patch anything
162+
description: Echo back PATCH request details
163+
operationId: patchAnything
164+
tags:
165+
- Echo
166+
requestBody:
167+
content:
168+
application/json:
169+
schema:
170+
type: object
171+
additionalProperties: true
172+
responses:
173+
'200':
174+
description: Successful response
175+
content:
176+
application/json:
177+
schema:
178+
$ref: '#/components/schemas/EchoResponse'
179+
'426':
180+
description: Upgrade Required (HTTPS redirect)
181+
182+
delete:
183+
summary: Delete anything
184+
description: Echo back DELETE request details
185+
operationId: deleteAnything
186+
tags:
187+
- Echo
188+
responses:
189+
'200':
190+
description: Successful response
191+
content:
192+
application/json:
193+
schema:
194+
$ref: '#/components/schemas/EchoResponse'
195+
'426':
196+
description: Upgrade Required (HTTPS redirect)
197+
198+
components:
199+
schemas:
200+
EchoResponse:
201+
type: object
202+
properties:
203+
args:
204+
type: object
205+
description: Query parameters
206+
data:
207+
type: string
208+
description: Request body data
209+
files:
210+
type: object
211+
description: Uploaded files
212+
form:
213+
type: object
214+
description: Form data
215+
headers:
216+
type: object
217+
description: Request headers
218+
json:
219+
type: object
220+
description: JSON request body
221+
method:
222+
type: string
223+
description: HTTP method used
224+
origin:
225+
type: string
226+
description: Origin IP address
227+
url:
228+
type: string
229+
description: Request URL
230+
231+
x-kong-service:
232+
name: example-service
233+
host: httpbin.konghq.com
234+
port: 80
235+
protocol: http
236+
path: /anything
237+
retries: 5
238+
connect_timeout: 60000
239+
write_timeout: 60000
240+
read_timeout: 60000
241+
242+
x-kong-route:
243+
name: example-route
244+
protocols: [http, https]
245+
methods: [GET, POST, PUT, PATCH, DELETE]
246+
paths: [/anything]
247+
strip_path: true
248+
preserve_host: false
249+
https_redirect_status_code: 426
250+
EOF
251+
```
252+
icon_url: /assets/icons/dev-portal.svg
253+
254+
255+
cleanup:
256+
inline:
257+
- title: Clean up {{site.konnect_short_name}} environment
258+
include_content: cleanup/platform/konnect
259+
icon_url: /assets/icons/gateway.svg
260+
---
261+
262+
You can compose [API packages](/catalog/api-packaging/) from existing APIs in Dev Portal. API packages allow you to:
263+
* Create distinct APIs for specific use cases or partners based on existing API operations.
264+
* Link to multiple Gateway Services and/or Routes for developer self-service and application registration.
265+
* Apply rate limiting policies to an API Package, or per operation.
266+
* Manage role-based access control for specific developers and teams.
267+
268+
## Associate a control plane
269+
270+
To allow developers to consume your API, you must first link an API Gateway and control plane to your API.
271+
272+
Operations from your API's OpenAPI spec should overlap with Routes to ensure requests will be routed to the correct Service. Gateway routing configuration isn't directly modified by adding operations.
273+
1. In the {{site.konnect_short_name}} sidebar, click [**Catalog**](https://cloud.konghq.com/apis/).
274+
1. Click **MyAPI**.
275+
1. Click the **Gateway** tab.
276+
1. Click **Link gateway**.
277+
1. From the **Control plane** dropdown menu, select "quickstart".
278+
1. Select **Link to a control plane**.
279+
1. In the Add the Access Control and Enforcement plugin settings, click **Add plugin**.
280+
1. Click **Link gateway**.
281+
1. Click the **API Specification** tab.
282+
1. Click **Upload Spec**.
283+
1. Click **Select file**.
284+
1. Select `example-api-spec.yaml`.
285+
1. Click **Save**.
286+
287+
## Assign operations to API packages
288+
289+
Now, you can create an API package by picking operations from your API. Operations are automatically mapped to Routes using your API's OpenAPI spec. The Gateway configuration isn't directly modified – any unmatched operations will be highlighted to indicate that a user needs Gateway Manager permissions to perform an action.
290+
291+
1. In the {{site.konnect_short_name}} sidebar, click **Catalog**.
292+
1. Click the **API packages** tab.
293+
1. Click **Create API package**.
294+
1. In the **API package name** field, enter `Company package`.
295+
1. Enable the Package rate limit.
296+
1. For the rate limit, enter `5` and select "Minute".
297+
1. In the API operations settings, click **Add operations from APIs**.
298+
1. In the Add API operations pane, click **MyAPI**
299+
1. For GET `/anything`, click **Add**.
300+
1. For PUT `/anything`, click **Add**.
301+
1. For POST `/anything`, click **Add**.
302+
1. Exit the Add API operations pane.
303+
1. Click **Create API package**.
304+
1. Click the **Specifications** tab.
305+
1. Click **Generate spec from operations**.
306+
1. Click **Save**.
307+
308+
## Publish API packages to Dev Portal
309+
Now you can make the API packages available to developers by publishing them to a Dev Portal.
310+
1. In the {{site.konnect_short_name}} sidebar, click **Catalog**.
311+
1. Click the **API packages** tab.
312+
1. Click **Company package**.
313+
1. Click **Publish API**.
314+
1. From the **Portal** dropdown menu, select your Dev Portal.
315+
1. From the **Authentication strategy** dropdown menu, select "Disabled".
316+
1. Click **Public**.
317+
1. Click **Publish API**.
318+
319+
Your API package will now be published to your Dev Portal. Published API packages appear the same as published APIs in the Dev Portal, and both allow developers to register applications with them.
320+
321+
## Validate
322+
323+
Now that you've published your API package, you can verify that it was successfully published by navigating to your Dev Portal's URL. You can find your Dev Portal's URL by navigating to the [Dev Portal overview](https://cloud.konghq.com/portals/) in the {{site.konnect_short_name}} UI.

‎app/_includes/prereqs/dev-portal-create-ui.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
For this tutorial, you’ll need a Dev Portal pre-configured. If you don't have these settings already configured, follow these steps to pre-configure it:
2+
3+
1. In the {{site.konnect_short_name}} sidebar, click **Dev Portal**.
4+
1. Click [**New portal**](https://cloud.konghq.com/portals/create).
5+
1. Enter a name for your Dev Portal.
6+
1. Click **Create and continue**.
7+
1. Customize your Dev Portal's appearance.
8+
1. Click **Save**.

‎app/_indices/catalog.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ sections:
1010
- path: /how-to/automate-api-catalog/
1111
- path: /how-to/automate-api-catalog-with-terraform/
1212
- path: /how-to/discover-and-govern-apis-with-service-catalog/
13+
- path: /how-to/package-apis-with-dev-portal/
1314
- title: Services and scorecards
1415
items:
1516
- path: /catalog/scorecards/

‎app/_indices/dev-portal.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ sections:
1515
- path: /catalog/api-packaging/
1616
- path: /how-to/automate-api-catalog/
1717
- path: /how-to/automate-api-catalog-with-terraform/
18+
- path: /how-to/package-apis-with-dev-portal/
1819
- title: Application registration
1920
items:
2021
- title: Developer sign-up

0 commit comments

Comments
 (0)