Skip to content

Commit 698d28a

Browse files
cloudjumpercatcloudjumpercat
committed
Add example spec, basic validate, fix some steps
Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com>
1 parent e454700 commit 698d28a

File tree

1 file changed

+183
-25
lines changed

1 file changed

+183
-25
lines changed

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

Lines changed: 183 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,177 @@ prereqs:
7676
```
7777
7878
To learn more about entities, you can read our [entities documentation](/gateway/entities).
79+
- title: API specification
80+
content: |
81+
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.
82+
83+
```sh
84+
cat > example-api-spec.yaml << 'EOF'
85+
openapi: 3.0.0
86+
info:
87+
title: Example API
88+
description: Example API service for testing and documentation
89+
version: 1.0.0
90+
91+
servers:
92+
- url: http://httpbin.konghq.com
93+
description: Backend service (HTTP only, port 80)
94+
95+
paths:
96+
/anything:
97+
get:
98+
summary: Get anything
99+
description: Echo back GET request details
100+
operationId: getAnything
101+
tags:
102+
- Echo
103+
responses:
104+
'200':
105+
description: Successful response
106+
content:
107+
application/json:
108+
schema:
109+
$ref: '#/components/schemas/EchoResponse'
110+
'426':
111+
description: Upgrade Required (HTTPS redirect)
112+
113+
post:
114+
summary: Post anything
115+
description: Echo back POST request details
116+
operationId: postAnything
117+
tags:
118+
- Echo
119+
requestBody:
120+
content:
121+
application/json:
122+
schema:
123+
type: object
124+
additionalProperties: true
125+
responses:
126+
'200':
127+
description: Successful response
128+
content:
129+
application/json:
130+
schema:
131+
$ref: '#/components/schemas/EchoResponse'
132+
'426':
133+
description: Upgrade Required (HTTPS redirect)
134+
135+
put:
136+
summary: Put anything
137+
description: Echo back PUT request details
138+
operationId: putAnything
139+
tags:
140+
- Echo
141+
requestBody:
142+
content:
143+
application/json:
144+
schema:
145+
type: object
146+
additionalProperties: true
147+
responses:
148+
'200':
149+
description: Successful response
150+
content:
151+
application/json:
152+
schema:
153+
$ref: '#/components/schemas/EchoResponse'
154+
'426':
155+
description: Upgrade Required (HTTPS redirect)
156+
157+
patch:
158+
summary: Patch anything
159+
description: Echo back PATCH request details
160+
operationId: patchAnything
161+
tags:
162+
- Echo
163+
requestBody:
164+
content:
165+
application/json:
166+
schema:
167+
type: object
168+
additionalProperties: true
169+
responses:
170+
'200':
171+
description: Successful response
172+
content:
173+
application/json:
174+
schema:
175+
$ref: '#/components/schemas/EchoResponse'
176+
'426':
177+
description: Upgrade Required (HTTPS redirect)
178+
179+
delete:
180+
summary: Delete anything
181+
description: Echo back DELETE request details
182+
operationId: deleteAnything
183+
tags:
184+
- Echo
185+
responses:
186+
'200':
187+
description: Successful response
188+
content:
189+
application/json:
190+
schema:
191+
$ref: '#/components/schemas/EchoResponse'
192+
'426':
193+
description: Upgrade Required (HTTPS redirect)
194+
195+
components:
196+
schemas:
197+
EchoResponse:
198+
type: object
199+
properties:
200+
args:
201+
type: object
202+
description: Query parameters
203+
data:
204+
type: string
205+
description: Request body data
206+
files:
207+
type: object
208+
description: Uploaded files
209+
form:
210+
type: object
211+
description: Form data
212+
headers:
213+
type: object
214+
description: Request headers
215+
json:
216+
type: object
217+
description: JSON request body
218+
method:
219+
type: string
220+
description: HTTP method used
221+
origin:
222+
type: string
223+
description: Origin IP address
224+
url:
225+
type: string
226+
description: Request URL
227+
228+
x-kong-service:
229+
name: example-service
230+
host: httpbin.konghq.com
231+
port: 80
232+
protocol: http
233+
path: /anything
234+
retries: 5
235+
connect_timeout: 60000
236+
write_timeout: 60000
237+
read_timeout: 60000
238+
239+
x-kong-route:
240+
name: example-route
241+
protocols: [http, https]
242+
methods: [GET, POST, PUT, PATCH, DELETE]
243+
paths: [/anything]
244+
strip_path: true
245+
preserve_host: false
246+
https_redirect_status_code: 426
247+
EOF
248+
```
249+
icon_url: /assets/icons/dev-portal.svg
79250

80251

81252
cleanup:
@@ -103,9 +274,16 @@ To allow developers to consume your API, you must first link an API Gateway and
103274
1. Select **Link to a control plane**.
104275
1. In the Add the Access Control and Enforcement plugin settings, click **Add plugin**.
105276
1. Click **Link gateway**.
277+
1. Click the **API Specification** tab.
278+
1. Click **Upload Spec**.
279+
1. Click **Select file**.
280+
1. Select `example-api-spec.yaml`.
281+
1. Click **Save**.
106282

107283
## Assign operations to API packages
108284

285+
Now, you can create an API package by picking operations from your API.
286+
109287
1. In the {{site.konnect_short_name}} sidebar, click **Catalog**.
110288
1. Click the **API packages** tab.
111289
1. Click **Create API package**.
@@ -119,8 +297,11 @@ To allow developers to consume your API, you must first link an API Gateway and
119297
1. For POST /anything, click **Add**.
120298
1. Exit the Add API operations pane.
121299
1. Click **Create API package**.
300+
1. Click the **Specifications** tab.
301+
1. Click **Generate spec from operations**.
302+
1. Click **Save**.
122303

123-
## Publish packages to Dev Portal
304+
## Publish API packages to Dev Portal
124305

125306
1. In the {{site.konnect_short_name}} sidebar, click **Catalog**.
126307
1. Click the **API packages** tab.
@@ -135,27 +316,4 @@ Your API package will now be published to your Dev Portal. Published API package
135316

136317
## Validate
137318

138-
Now that you've published your API package with a rate limit of 5 requests per minute, you can validate that the rate limiting is working correctly.
139-
140-
Run the following command to send 11 GET requests to your API.
141-
```bash
142-
for _ in {1..11}; do
143-
curl -i -X GET http://localhost:8000/anything
144-
echo
145-
done
146-
```
147-
148-
**Expected results:**
149-
150-
* The first 5 requests should return `HTTP/1.1 200 OK`
151-
* Requests 6-11 should return `HTTP/1.1 429 Too Many Requests` with a response body indicating the rate limit has been exceeded:
152-
```json
153-
{
154-
"message": "API rate limit exceeded"
155-
}
156-
```
157-
158-
The ACE plugin enforces the rate limit you configured (5 requests per minute) on the API package, protecting your backend service from excessive requests.
159-
160-
{:.note}
161-
> **Note:** If you don't include the `apikey` header, the request may still succeed if the ACE plugin is configured with `config.enforce_consumer_groups: if_present`. To test unauthenticated access, try the same command without the `-H "apikey: YOUR_API_KEY"` header.
319+
Now that you've published your API package, you can verify that it was successfully published to your Dev Portal's URL.

0 commit comments

Comments
 (0)