zuplo 7.8.12 → 7.8.14
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/dev-portal/overview.mdx +49 -45
- package/docs/handlers/mcp-server.mdx +8 -6
- package/docs/mcp-server/overview.mdx +51 -106
- package/docs/mcp-server/tools.mdx +69 -15
- package/docs/mcp-server/troubleshooting.mdx +7 -7
- package/docs/policies/_index.md +1 -1
- package/docs/policies/ai-gateway-auth-v2-inbound/schema.json +1 -1
- package/docs/policies/ai-gateway-smart-router-inbound/doc.md +16 -4
- package/docs/policies/ai-gateway-smart-router-inbound/schema.json +18 -14
- package/docs/programmable-api/overview.mdx +84 -177
- package/package.json +5 -5
|
@@ -6,63 +6,67 @@ description:
|
|
|
6
6
|
authentication, and API key self-service.
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
Portal powers this documentation site and is available for all Zuplo users.
|
|
9
|
+
<span id="what-is-the-dev-portal" />
|
|
11
10
|
|
|
12
|
-
|
|
11
|
+
The Zuplo Developer Portal gives your API consumers a place to read
|
|
12
|
+
documentation, explore your API, and manage their API keys. It combines API
|
|
13
|
+
reference documentation from your OpenAPI specifications with pages you write in
|
|
14
|
+
Markdown, MDX, or React.
|
|
13
15
|
|
|
14
|
-
|
|
16
|
+
<span id="build-deploy-and-hosting" />
|
|
15
17
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
provides a seamless experience for developers to consume your APIs.
|
|
18
|
+
Zuplo builds, deploys, and hosts the portal. The portal uses Zudoku for content,
|
|
19
|
+
configuration, and customization.
|
|
19
20
|
|
|
20
|
-
|
|
21
|
+
<Framed>
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
customizable experience. It is easy to use out of the box, but also allows for
|
|
24
|
-
advanced customization for those who want to take it to the next level. The new
|
|
25
|
-
Developer Portal is built on top of Zudoku, which is a powerful static site
|
|
26
|
-
generator that allows for advanced customization and theming. Zudoku is built on
|
|
27
|
-
Vite which allows for fast builds and a great developer experience.
|
|
23
|
+
|
|
28
24
|
|
|
29
|
-
|
|
25
|
+
</Framed>
|
|
30
26
|
|
|
31
|
-
|
|
32
|
-
manage your API documentation. Some of the key features include:
|
|
27
|
+
<span id="what-features-are-available" />
|
|
33
28
|
|
|
34
|
-
|
|
35
|
-
automatically converted to HTML.
|
|
36
|
-
- **API Documentation**: Automatically generate API documentation from your
|
|
37
|
-
OpenAPI specifications.
|
|
38
|
-
- **API Explorer**: Explore and test your API directly from the documentation.
|
|
39
|
-
- **Custom Pages**: Create custom pages for your documentation using Markdown,
|
|
40
|
-
MDX, or even React.
|
|
41
|
-
- **Custom Modules**: Install custom modules to extend the functionality of your
|
|
42
|
-
documentation.
|
|
43
|
-
- **API Key Management**: When using Zuplo's API Key management, manage API keys
|
|
44
|
-
directly from the documentation.
|
|
45
|
-
- **Built-in Analytics**: End users can see how they are using the API, monitor
|
|
46
|
-
usage of their API keys, and more right from inside the portal.
|
|
29
|
+
## What you can do
|
|
47
30
|
|
|
48
|
-
|
|
31
|
+
Use the Developer Portal to:
|
|
49
32
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
33
|
+
- Generate API reference documentation from your OpenAPI specifications and let
|
|
34
|
+
readers test requests in the API Explorer.
|
|
35
|
+
- Publish guides and custom pages in Markdown, MDX, or React.
|
|
36
|
+
- Let consumers manage their keys when you use Zuplo's API key management.
|
|
37
|
+
- Show subscription quota usage with the
|
|
38
|
+
[monetization usage dashboard](../articles/monetization/developer-portal.md#usage-dashboard).
|
|
39
|
+
- Customize the portal's theme, install modules, and use a custom domain.
|
|
53
40
|
|
|
54
|
-
|
|
41
|
+
<span id="why-the-new-dev-portal" />
|
|
55
42
|
|
|
56
|
-
|
|
57
|
-
Simply sign up for Zuplo, create a new project, and you will have a fully
|
|
58
|
-
functioning developer portal in minutes. Zuplo handles all the hosting and
|
|
59
|
-
deployment for you, so you can focus on building your API and documentation.
|
|
43
|
+
## Core concepts
|
|
60
44
|
|
|
61
|
-
|
|
62
|
-
brand. Learn more in the
|
|
63
|
-
[Custom Domains documentation](/docs/articles/custom-domains).
|
|
45
|
+
The portal combines three parts:
|
|
64
46
|
|
|
65
|
-
|
|
47
|
+
| Part | Purpose |
|
|
48
|
+
| -------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
49
|
+
| OpenAPI specifications | Describe the API operations shown in the reference and API Explorer. |
|
|
50
|
+
| Documentation pages | Provide guides and other content you write for your API consumers. |
|
|
51
|
+
| [Configuration file](./zudoku/configuration/overview.md) | Set navigation, appearance, authentication, and other portal options. |
|
|
66
52
|
|
|
67
|
-
|
|
68
|
-
|
|
53
|
+
You can [work on the portal locally](../getting-started/dev-portal/local.mdx) to
|
|
54
|
+
preview content and configuration changes before deployment. Zuplo manages
|
|
55
|
+
hosting, and you can assign a [custom domain](../articles/custom-domains.mdx)
|
|
56
|
+
such as `docs.example.com`.
|
|
57
|
+
|
|
58
|
+
<span id="how-to-get-started" />
|
|
59
|
+
|
|
60
|
+
## Next steps
|
|
61
|
+
|
|
62
|
+
- [Build your first developer portal](../getting-started/dev-portal/portal.mdx)
|
|
63
|
+
in the Zuplo Portal, then test an authenticated API request.
|
|
64
|
+
- Review the [configuration file](./zudoku/configuration/overview.md) to set up
|
|
65
|
+
your portal's content and navigation.
|
|
66
|
+
- [Add a custom domain](../articles/custom-domains.mdx) for your published
|
|
67
|
+
portal.
|
|
68
|
+
|
|
69
|
+
<span id="feedback" />
|
|
70
|
+
|
|
71
|
+
For help with your developer portal, contact
|
|
72
|
+
[support@zuplo.com](mailto:support@zuplo.com).
|
|
@@ -98,12 +98,14 @@ The MCP Server handler supports the following configuration options:
|
|
|
98
98
|
- `operations` - An array of operation references to register with the MCP
|
|
99
99
|
server. Each operation can be a tool, prompt, or resource based on its
|
|
100
100
|
`x-zuplo-route.mcp` configuration.
|
|
101
|
-
- `toolInputStyle` (optional, default `
|
|
102
|
-
operation's inputs. With `
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
101
|
+
- `toolInputStyle` (optional, default `nested`) - How generated tools advertise
|
|
102
|
+
an operation's inputs. With `nested`, each input channel stays its own object
|
|
103
|
+
(`body`, `queryParams`, `pathParams`, `headers`). With `flat`, a request
|
|
104
|
+
body's properties and the operation's path, query, and header parameters all
|
|
105
|
+
become top-level tool arguments. Flat tools accept the nested form too, so
|
|
106
|
+
switching to `flat` doesn't break existing clients. This option sets the
|
|
107
|
+
default for every tool on the server. A tool can override it with
|
|
108
|
+
`toolInputStyle` in its route's `x-zuplo-route.mcp` block. See
|
|
107
109
|
[Tool input schemas](../mcp-server/tools.mdx#tool-input-schemas).
|
|
108
110
|
|
|
109
111
|
### MCP `2025-06-18` Global Options
|
|
@@ -6,130 +6,75 @@ description:
|
|
|
6
6
|
with Zuplo's MCP Server handler.
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
an open protocol that enables controlled interactions between AI systems and
|
|
11
|
-
agents. It enables external tools and data sources to be utilized and read by AI
|
|
12
|
-
agents that implement the protocol.
|
|
9
|
+
<span id="whats-mcp" />
|
|
13
10
|
|
|
14
|
-
|
|
15
|
-
|
|
11
|
+
The Zuplo MCP Server handler exposes your API routes to AI clients through the
|
|
12
|
+
Model Context Protocol (MCP). It uses your OpenAPI definitions to describe the
|
|
13
|
+
operations a client can discover and call.
|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
Use it to make your own API available through MCP. To connect clients to MCP
|
|
16
|
+
servers that already exist, see the
|
|
17
|
+
[MCP Gateway overview](../mcp-gateway/overview.mdx).
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
into an MCP server. If you want to put a single OAuth-protected endpoint in
|
|
21
|
-
front of one or more existing upstream MCP servers (Linear, Stripe, Notion,
|
|
22
|
-
internal services, etc.), see the
|
|
23
|
-
[MCP Gateway overview](../mcp-gateway/overview.mdx) instead.
|
|
19
|
+
<span id="how-zuplo-enables-mcp" />
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
## What you can do
|
|
26
22
|
|
|
27
|
-
|
|
23
|
+
With the MCP Server handler, you can:
|
|
28
24
|
|
|
29
|
-
|
|
30
|
-
|
|
25
|
+
- Expose API operations as tools, such as looking up a customer or creating a
|
|
26
|
+
support ticket.
|
|
27
|
+
- Provide reusable prompt templates and read-only resources alongside your
|
|
28
|
+
tools.
|
|
29
|
+
- Apply authentication, rate limiting, and access controls with Zuplo policies.
|
|
30
|
+
- Track tool usage through logging and analytics.
|
|
31
31
|
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
- Custom business backends and workflows
|
|
32
|
+
<span id="mcp-implementation-options" />
|
|
33
|
+
<span id="1-mcp-server-handler-transform-routes-into-ai-tools" />
|
|
34
|
+
<span id="how-it-works" />
|
|
36
35
|
|
|
37
|
-
|
|
36
|
+
## Core concepts
|
|
38
37
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
message flow.
|
|
42
|
-
- **Standardized**: Consistent interface across different tools, servers,
|
|
43
|
-
clients, languages, and services.
|
|
38
|
+
An MCP server runs on a route in your Zuplo project. You configure which OpenAPI
|
|
39
|
+
operations it exposes and how clients use each operation:
|
|
44
40
|
|
|
45
|
-
|
|
41
|
+
| Capability | Purpose |
|
|
42
|
+
| ---------------------------- | ------------------------------------------------------------ |
|
|
43
|
+
| [Tools](./tools.mdx) | Call an API operation to retrieve data or perform an action. |
|
|
44
|
+
| [Prompts](./prompts.mdx) | Request a reusable prompt template with parameters. |
|
|
45
|
+
| [Resources](./resources.mdx) | Read data or documents through a resource URI. |
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
|
|
47
|
+
The MCP Server handler invokes the configured route in your gateway, including
|
|
48
|
+
that route's policies. For configuration options, see the
|
|
49
|
+
[MCP Server handler reference](../handlers/mcp-server.mdx).
|
|
49
50
|
|
|
50
|
-
|
|
51
|
-
standardized MCP-compatible server
|
|
52
|
-
2. **Security & Control**: Built-in authentication, rate limiting, and access
|
|
53
|
-
controls
|
|
54
|
-
3. **Monitoring & Analytics**: Full observability into AI tool usage and
|
|
55
|
-
performance
|
|
56
|
-
4. **Developer Experience**: Easy configuration and deployment using your
|
|
57
|
-
existing OpenAPI specifications
|
|
51
|
+
### Example use cases
|
|
58
52
|
|
|
59
|
-
|
|
60
|
-
toolset that AI systems can discover, understand, and invoke - bringing AI
|
|
61
|
-
capabilities directly into your business workflows!
|
|
53
|
+
You can expose operations such as these as MCP tools:
|
|
62
54
|
|
|
63
|
-
|
|
55
|
+
| Use case | Example operations |
|
|
56
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
57
|
+
| <span id="customer-service-ai-tools" />Customer service | Look up a customer with `GET /customers/{id}`, create a ticket with `POST /tickets`, or update a status with `PUT /customers/{id}/status`. |
|
|
58
|
+
| <span id="e-commerce-ai-assistant" />E-commerce | Search products with `GET /products/search`, add an item with `POST /cart/add`, or check an order with `GET /orders/{id}`. |
|
|
59
|
+
| <span id="devops-automation" />DevOps | List deployments with `GET /deployments`, create a deployment with `POST /deployments`, or retrieve metrics with `GET /metrics`. |
|
|
64
60
|
|
|
65
|
-
|
|
61
|
+
For workflows that combine several operations, use
|
|
62
|
+
[custom tools](./custom-tools.mdx).
|
|
66
63
|
|
|
67
|
-
|
|
64
|
+
<span id="security-considerations" />
|
|
68
65
|
|
|
69
|
-
|
|
70
|
-
tools that AI systems can discover and use.
|
|
66
|
+
## Secure your MCP server
|
|
71
67
|
|
|
72
|
-
|
|
68
|
+
Expose only the operations your clients need. Apply authentication and access
|
|
69
|
+
controls to those operations, use rate limits to control usage, and configure
|
|
70
|
+
[audit logging](../articles/audit-logging.mdx) to record calls.
|
|
73
71
|
|
|
74
|
-
|
|
72
|
+
<span id="learn-more" />
|
|
75
73
|
|
|
76
|
-
|
|
77
|
-
MCP tools
|
|
78
|
-
2. **OpenAPI Integration**: Uses your existing OpenAPI specifications to provide
|
|
79
|
-
tool descriptions
|
|
80
|
-
3. **Secure Access**: Leverages Zuplo's authentication and authorization
|
|
81
|
-
policies
|
|
82
|
-
4. **Real-time Execution**: AI systems can invoke your routes as tools in
|
|
83
|
-
real-time
|
|
74
|
+
## Next steps
|
|
84
75
|
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
```
|
|
92
|
-
- GET /customers/{id} → "Get customer information for user 123"
|
|
93
|
-
- POST /tickets → "Create a support ticket with the following ..."
|
|
94
|
-
- PUT /customers/{id}/status → "Update customer 123 status ..."
|
|
95
|
-
```
|
|
96
|
-
|
|
97
|
-
##### E-commerce AI Assistant
|
|
98
|
-
|
|
99
|
-
Expose your e-commerce APIs as shopping tools:
|
|
100
|
-
|
|
101
|
-
```
|
|
102
|
-
- GET /products/search → "Search for products ..."
|
|
103
|
-
- POST /cart/add → "Add item to cart"
|
|
104
|
-
- GET /orders/{id} → "Get order status"
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
##### DevOps Automation
|
|
108
|
-
|
|
109
|
-
Make your infrastructure APIs available to AI:
|
|
110
|
-
|
|
111
|
-
```
|
|
112
|
-
- GET /deployments → "List deployments"
|
|
113
|
-
- POST /deployments → "Create new deployment"
|
|
114
|
-
- GET /metrics → "Get system metrics"
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
#### Security Considerations
|
|
118
|
-
|
|
119
|
-
When exposing routes as MCP tools:
|
|
120
|
-
|
|
121
|
-
1. **Apply appropriate authentication policies** to ensure only authorized AI
|
|
122
|
-
systems can access your tools
|
|
123
|
-
2. **Use rate limiting** to prevent abuse and control usage costs
|
|
124
|
-
3. **Implement audit logging** to track tool usage and maintain compliance
|
|
125
|
-
4. **Scope permissions carefully** - only expose routes and OpenAPI specs that
|
|
126
|
-
should be accessible to AI systems
|
|
127
|
-
|
|
128
|
-
## Learn More
|
|
129
|
-
|
|
130
|
-
- [MCP Server Handler Technical Documentation](../handlers/mcp-server.mdx)
|
|
131
|
-
- [MCP Tools Documentation](./tools.mdx)
|
|
132
|
-
- [MCP Prompts Documentation](./prompts.mdx)
|
|
133
|
-
- [MCP Resources Documentation](./resources.mdx)
|
|
134
|
-
- [MCP Custom Tools Documentation](./custom-tools.mdx)
|
|
135
|
-
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
|
|
76
|
+
- Follow the [MCP Server quickstart](../getting-started/mcp-server/portal.mdx)
|
|
77
|
+
to expose an API and connect an MCP client.
|
|
78
|
+
- [Configure tools](./tools.mdx), including their names, descriptions, and input
|
|
79
|
+
schemas.
|
|
80
|
+
- [Test your MCP server](./testing.mdx) to check the capabilities it exposes.
|
|
@@ -76,6 +76,20 @@ The `x-zuplo-route.mcp` configuration for tools supports:
|
|
|
76
76
|
description.
|
|
77
77
|
- `enabled` (`boolean`: optional) - Whether this tool is enabled. Defaults to
|
|
78
78
|
`true`.
|
|
79
|
+
- `includeOutputSchema` (`boolean`: optional) - Whether to advertise the route's
|
|
80
|
+
successful (2xx) response schema as the tool's `outputSchema`. Overrides the
|
|
81
|
+
handler's
|
|
82
|
+
[`includeOutputSchema`](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options)
|
|
83
|
+
option for this tool.
|
|
84
|
+
- `includeStructuredContent` (`boolean`: optional) - Whether to return the
|
|
85
|
+
response JSON as `structuredContent`. Overrides the handler's
|
|
86
|
+
[`includeStructuredContent`](../handlers/mcp-server.mdx#mcp-2025-06-18-global-options)
|
|
87
|
+
option for this tool. Turns on automatically when `includeOutputSchema` is
|
|
88
|
+
`true`.
|
|
89
|
+
- `toolInputStyle` (`string`: optional) - `"flat"` or `"nested"`. How this tool
|
|
90
|
+
advertises the operation's inputs. Overrides the handler's
|
|
91
|
+
[`toolInputStyle`](../handlers/mcp-server.mdx#configuration) option for this
|
|
92
|
+
tool. See [Set the input style per tool](#set-the-input-style-per-tool).
|
|
79
93
|
- `annotations` (`object`: optional) - An object containing tool annotations:
|
|
80
94
|
- `title` (`string`: optional) - A human-readable title for the tool, often
|
|
81
95
|
used by clients.
|
|
@@ -142,17 +156,26 @@ See further details in the
|
|
|
142
156
|
|
|
143
157
|
## Tool input schemas
|
|
144
158
|
|
|
145
|
-
Zuplo derives each tool's `inputSchema` from the operation's OpenAPI definition
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
159
|
+
Zuplo derives each tool's `inputSchema` from the operation's OpenAPI definition.
|
|
160
|
+
The `toolInputStyle` setting decides its shape:
|
|
161
|
+
|
|
162
|
+
- `nested` (default) - Each input channel the operation declares is its own
|
|
163
|
+
object argument: `body`, `queryParams`, `pathParams`, or `headers`.
|
|
164
|
+
- `flat` - The request body's properties and the operation's path, query, and
|
|
165
|
+
header parameters all become top-level tool arguments. This is the shape MCP
|
|
166
|
+
clients send on a first call.
|
|
167
|
+
|
|
168
|
+
Set `toolInputStyle` in the
|
|
169
|
+
[handler options](../handlers/mcp-server.mdx#configuration) to choose the style
|
|
170
|
+
for every tool on the server. To give one tool a different style, see
|
|
171
|
+
[Set the input style per tool](#set-the-input-style-per-tool).
|
|
149
172
|
|
|
150
|
-
When a client calls
|
|
173
|
+
When a client calls a flat tool, the gateway routes each argument back to the
|
|
151
174
|
channel it came from, so a body field lands in the request body and a query
|
|
152
175
|
parameter lands in the URL.
|
|
153
176
|
|
|
154
|
-
The weather route above declares one required query parameter, so its tool
|
|
155
|
-
one required argument:
|
|
177
|
+
The weather route above declares one required query parameter, so its flat tool
|
|
178
|
+
takes one required argument:
|
|
156
179
|
|
|
157
180
|
```json
|
|
158
181
|
{
|
|
@@ -196,7 +219,7 @@ this operation:
|
|
|
196
219
|
}
|
|
197
220
|
```
|
|
198
221
|
|
|
199
|
-
|
|
222
|
+
A flat tool advertises the body's fields directly:
|
|
200
223
|
|
|
201
224
|
```json
|
|
202
225
|
{
|
|
@@ -247,8 +270,8 @@ that exact name. An undeclared argument never becomes an upstream header.
|
|
|
247
270
|
### When arguments stay nested
|
|
248
271
|
|
|
249
272
|
Some operations can't be flattened without changing what the tool accepts. Those
|
|
250
|
-
tools keep the nested shape
|
|
251
|
-
registers the tool:
|
|
273
|
+
tools keep the nested shape even when `toolInputStyle` is `flat`, and the MCP
|
|
274
|
+
server logs the reason when it registers the tool:
|
|
252
275
|
|
|
253
276
|
- **Two channels declare the same name.** A `limit` query parameter alongside a
|
|
254
277
|
`limit` body field, for example. The whole schema stays nested and the server
|
|
@@ -296,11 +319,7 @@ schema keeps working:
|
|
|
296
319
|
}
|
|
297
320
|
```
|
|
298
321
|
|
|
299
|
-
Send flat arguments in new clients — that's what
|
|
300
|
-
|
|
301
|
-
To make every generated tool advertise the nested shape instead, set
|
|
302
|
-
[`toolInputStyle: "nested"`](../handlers/mcp-server.mdx#configuration) in the
|
|
303
|
-
handler options.
|
|
322
|
+
Send flat arguments in new clients — that's what a flat tool advertises.
|
|
304
323
|
|
|
305
324
|
:::note
|
|
306
325
|
|
|
@@ -310,6 +329,41 @@ top level.
|
|
|
310
329
|
|
|
311
330
|
:::
|
|
312
331
|
|
|
332
|
+
### Set the input style per tool
|
|
333
|
+
|
|
334
|
+
Set `toolInputStyle` in a route's `x-zuplo-route.mcp` block to give that tool a
|
|
335
|
+
different input style from the rest of the server:
|
|
336
|
+
|
|
337
|
+
```json
|
|
338
|
+
"x-zuplo-route": {
|
|
339
|
+
"mcp": { "type": "tool", "toolInputStyle": "flat" }
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
Each tool uses the first value it finds:
|
|
344
|
+
|
|
345
|
+
1. The tool's own `toolInputStyle`.
|
|
346
|
+
2. The handler's `toolInputStyle` option.
|
|
347
|
+
3. `nested`.
|
|
348
|
+
|
|
349
|
+
The override works in either direction: a `flat` tool on a nested server, or a
|
|
350
|
+
`nested` tool on a flat server. Use it to add tools with flat inputs to an
|
|
351
|
+
existing MCP server without changing the schema its current tools advertise, and
|
|
352
|
+
without creating a second MCP route. Flat tools still accept nested arguments,
|
|
353
|
+
so switching one tool to `flat` doesn't break existing callers. Only that tool's
|
|
354
|
+
advertised `inputSchema` changes.
|
|
355
|
+
|
|
356
|
+
`toolInputStyle` accepts only `"flat"` or `"nested"`. The build rejects any
|
|
357
|
+
other value in `x-zuplo-route.mcp`. The MCP server also checks the value when it
|
|
358
|
+
registers the tool and throws an error that names the operation:
|
|
359
|
+
|
|
360
|
+
```
|
|
361
|
+
MCP tool configuration error: invalid toolInputStyle "Flat" on operation "createOrder". Use "flat" or "nested".
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
If your MCP server still uses the deprecated `files` option, set
|
|
365
|
+
`toolInputStyle` in the operation's `x-zuplo-mcp-tool` extension instead.
|
|
366
|
+
|
|
313
367
|
## Testing MCP Tools
|
|
314
368
|
|
|
315
369
|
### List Available Tools
|
|
@@ -165,9 +165,9 @@ is closed and an argument it doesn't declare is invalid. Read the tool's
|
|
|
165
165
|
`inputSchema` from `tools/list` and compare the argument names. A model that
|
|
166
166
|
invents a field name lands here.
|
|
167
167
|
|
|
168
|
-
**Likely cause 2: the tool takes nested arguments.**
|
|
169
|
-
|
|
170
|
-
|
|
168
|
+
**Likely cause 2: the tool takes nested arguments.** A tool takes nested
|
|
169
|
+
arguments when its [`toolInputStyle`](./tools.mdx#tool-input-schemas) is
|
|
170
|
+
`nested`, which is the default, or when its OpenAPI can't be flattened. Its
|
|
171
171
|
arguments sit under `body`, `queryParams`, `pathParams`, or `headers`. When the
|
|
172
172
|
error reads `at body`, the caller sent flat arguments to a nested tool:
|
|
173
173
|
|
|
@@ -177,10 +177,10 @@ error reads `at body`, the caller sent flat arguments to a nested tool:
|
|
|
177
177
|
→ at body
|
|
178
178
|
```
|
|
179
179
|
|
|
180
|
-
|
|
181
|
-
it registers the tool: a name collision between two input channels (logged
|
|
182
|
-
warning), or a request body that isn't a plain object (logged at debug
|
|
183
|
-
enable `debugMode` to see it). See
|
|
180
|
+
When a `flat` tool still advertises nested arguments, the MCP server logs why
|
|
181
|
+
when it registers the tool: a name collision between two input channels (logged
|
|
182
|
+
as a warning), or a request body that isn't a plain object (logged at debug
|
|
183
|
+
level — enable `debugMode` to see it). See
|
|
184
184
|
[When arguments stay nested](./tools.mdx#when-arguments-stay-nested) for both
|
|
185
185
|
cases and how to resolve the collision.
|
|
186
186
|
|
package/docs/policies/_index.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
| --- | --- | --- | --- |
|
|
5
5
|
| set-query-params-inbound | Add or Set Query Parameters | Adds or sets query parameters on the incoming request. | api-gateway |
|
|
6
6
|
| set-headers-inbound | Add or Set Request Headers | Adds or sets headers on the incoming request. | api-gateway |
|
|
7
|
-
| ai-gateway-auth-v2-inbound | AI Gateway Authentication | Authenticates requests to an AI Gateway endpoint with application API keys. Add this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential. When the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires
|
|
7
|
+
| ai-gateway-auth-v2-inbound | AI Gateway Authentication | Authenticates requests to an AI Gateway endpoint with application API keys. Add this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential. When the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires the stored configuration ID to match the URL (adding `config_` for `/a`). It returns 403 on mismatch. | ai-gateway |
|
|
8
8
|
| ai-gateway-configuration-executor-v2-inbound | AI Gateway Configuration Executor | Loads the app configuration for the request (when auth or the configuration loader has not already), runs the inbound policy chain from that configuration, and enforces limits inherited from parent teams or the gateway root. Place this policy on AI Gateway routes after optional authentication and optional `ai-gateway-configuration-loader-v2-inbound`. When either of those already populated the app-configuration channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter. Applications select from policies pre-declared by the gateway. Applications without a `inboundPolicyChain`, or with an empty chain, run no application-selected policies. Entry options replace the declaration's options as a complete object; omit them to inherit the declaration, including environment-backed credentials. Each occurrence receives a private deep copy of its entry options, so a policy mutating its options cannot corrupt the cached app configuration. | ai-gateway |
|
|
9
9
|
| ai-gateway-configuration-loader-v2-inbound | AI Gateway Configuration Loader | Loads the AI Gateway app configuration for the request into the request-scoped channel and does nothing else. Place this policy on AI Gateway routes before `ai-gateway-configuration-executor-v2-inbound` when you want configuration loading separated from chain execution. When `ai-gateway-auth-v2-inbound` already populated the channel, this policy reuses it. Otherwise it loads the configuration with the route's `app_id` path parameter. If this policy is omitted, the configuration executor still loads configuration itself before running the application chain. | ai-gateway |
|
|
10
10
|
| ai-gateway-fallback-model-v2-inbound | AI Gateway Fallback Model | Adds failure and quota fallbacks to an existing AI Gateway model selection. Place this policy after AI Gateway Model Filtering. It never creates a model selection, so a misplaced policy cannot bypass filtering. | ai-gateway |
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
"requiresAI": true,
|
|
13
13
|
"policyType": "ai-gateway-auth-v2",
|
|
14
14
|
"products": ["ai-gateway"],
|
|
15
|
-
"description": "Authenticates requests to an AI Gateway endpoint with application API keys.\n\nAdd this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential.\n\nWhen the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires
|
|
15
|
+
"description": "Authenticates requests to an AI Gateway endpoint with application API keys.\n\nAdd this policy to an application's `inboundPolicyChain` to require a key for that app only, or place it on the route before the configuration executor to require a key for every application on the route. The policies that follow can read the authenticated application from `request.user` (`sub` is the application name, `data` its metadata), and the application's AI Gateway configuration takes effect for the request. Use `authHeader` and `authScheme` when clients send their app key somewhere other than the default `Authorization: Bearer` header. Enable `credentialPassthrough`, with the application key in a separate header, to forward the caller's `Authorization` header to the primary provider as its credential.\n\nWhen the matched route captures an `app_id` path parameter (platform catch-all `/:app_id/(.*)`), this policy also requires the stored configuration ID to match the URL (adding `config_` for `/a`). It returns 403 on mismatch.",
|
|
16
16
|
"deprecatedMessage": "",
|
|
17
17
|
"required": ["handler"],
|
|
18
18
|
"properties": {
|
|
@@ -2,8 +2,10 @@ Use this policy to classify the last user prompt on Chat Completions, Responses,
|
|
|
2
2
|
and Anthropic Messages requests. Using the classification results, configure
|
|
3
3
|
where to route the request based on its complexity.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
the configuration in `modelsByComplexity`.
|
|
5
|
+
Smart routing is on by default: the policy overwrites completions routing based
|
|
6
|
+
on the configuration in `modelsByComplexity`. Set `smartRoutingEnabled` to
|
|
7
|
+
`false` to keep classifying without routing, which is useful when testing a
|
|
8
|
+
classifier prompt.
|
|
7
9
|
|
|
8
10
|
> **Classification failure handling.** If the message classification fails or
|
|
9
11
|
> times out, the request is forwarded to the original model.
|
|
@@ -14,7 +16,16 @@ the configuration in `modelsByComplexity`.
|
|
|
14
16
|
runs the classifier.
|
|
15
17
|
- `classifierModel` — `providerName/model` sent on the classifier request.
|
|
16
18
|
- `modelsByComplexity` — `providerName/model` for each of `low`, `medium`, and
|
|
17
|
-
`high`. Used for routing
|
|
19
|
+
`high`. Used for routing unless `smartRoutingEnabled` is set to `false`.
|
|
20
|
+
|
|
21
|
+
Give the classifier its own application rather than pointing this at the app the
|
|
22
|
+
policy runs on. The classifier request never leaves the gateway, so that
|
|
23
|
+
application needs no API key checked at all — put the Ensure Gateway Internal
|
|
24
|
+
Invocation Only policy on it in place of API Key Authentication.
|
|
25
|
+
|
|
26
|
+
`classifierAppApiKey` is only for a classifier app that does check API keys: a
|
|
27
|
+
bearer token for it, typically `$env(CLASSIFIER_APP_API_KEY)`. Omit it, or leave
|
|
28
|
+
it empty, and the classifier request carries no `Authorization` header.
|
|
18
29
|
|
|
19
30
|
Omit `intents` and `classifierPrompt` to use the built-in dictionary (code,
|
|
20
31
|
summarization, translation, qa, conversation, classification, creative_writing,
|
|
@@ -89,7 +100,7 @@ Complexity is classified independently of intent, as `low`, `medium`, or `high`.
|
|
|
89
100
|
Smart Router looks up `modelsByComplexity[complexity]` and applies it only when
|
|
90
101
|
**all** of the following hold:
|
|
91
102
|
|
|
92
|
-
- `smartRoutingEnabled` is `true
|
|
103
|
+
- `smartRoutingEnabled` is `true` (the default).
|
|
93
104
|
- The classified intent is a known one (not capped as an unknown intent).
|
|
94
105
|
- `modelsByComplexity` has a model configured for that complexity.
|
|
95
106
|
- `profile.confidence >= minConfidenceForRouting` (default `0.5`).
|
|
@@ -103,6 +114,7 @@ to see why: `disabled`, `unknown-intent`, `no-model`, `low-confidence`,
|
|
|
103
114
|
|
|
104
115
|
| Option | Default | Purpose |
|
|
105
116
|
| ------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `smartRoutingEnabled` | `true` | Set it to `false` to classify every request and record the result without changing which model serves the request. |
|
|
106
118
|
| `minConfidenceForRouting` | `0.5` | Raise it to route only on confident classifications; lower it to route more aggressively. Unknown intents are always capped just below this value, so they never qualify regardless of the setting. |
|
|
107
119
|
| `classifierTimeoutMs` | `8000` | How long to wait for the classifier before giving up and forwarding the request unclassified. |
|
|
108
120
|
| `maxPromptChars` | `8000` | Truncates the prompt sent to the classifier, to keep classifier cost and latency bounded on very long prompts. |
|
|
@@ -59,12 +59,6 @@
|
|
|
59
59
|
"description": "The AI Gateway application id used to run the classifier prompt and evaluate the user's request.",
|
|
60
60
|
"examples": ["config_1234"]
|
|
61
61
|
},
|
|
62
|
-
"classifierAppApiKey": {
|
|
63
|
-
"type": "string",
|
|
64
|
-
"title": "Classifier App API Key",
|
|
65
|
-
"description": "API key sent as `Authorization: Bearer` when invoking the classifier app. Omit it when the classifier app runs the Ensure Gateway Internal Invocation Only policy: the classifier call never leaves the gateway, so that policy accepts it and rejects everything arriving over the network, and no credential is sent. Set it only when the classifier app authenticates callers with API keys.",
|
|
66
|
-
"examples": ["$env(CLASSIFIER_APP_API_KEY)"]
|
|
67
|
-
},
|
|
68
62
|
"classifierModel": {
|
|
69
63
|
"type": "string",
|
|
70
64
|
"title": "Classifier Model",
|
|
@@ -72,12 +66,6 @@
|
|
|
72
66
|
"pattern": "^[^/\\s]+/.+$",
|
|
73
67
|
"examples": ["openai/gpt-4o-mini"]
|
|
74
68
|
},
|
|
75
|
-
"smartRoutingEnabled": {
|
|
76
|
-
"type": "boolean",
|
|
77
|
-
"title": "Smart Routing Enabled",
|
|
78
|
-
"description": "When true, apply model routing based on the models set in `modelsByComplexity` when confidence score meets the `minConfidenceForRouting` threshold. When set to false, classification still runs but model routing is not applied, useful for debugging or testing the classifier prompt.",
|
|
79
|
-
"default": false
|
|
80
|
-
},
|
|
81
69
|
"modelsByComplexity": {
|
|
82
70
|
"type": "object",
|
|
83
71
|
"title": "Models By Complexity",
|
|
@@ -108,6 +96,20 @@
|
|
|
108
96
|
}
|
|
109
97
|
}
|
|
110
98
|
},
|
|
99
|
+
"classifierAppApiKey": {
|
|
100
|
+
"type": "string",
|
|
101
|
+
"title": "Classifier App API Key",
|
|
102
|
+
"description": "API key sent as `Authorization: Bearer` when invoking the classifier app. Omit it when the classifier app runs the Ensure Gateway Internal Invocation Only policy: the classifier call never leaves the gateway, so that policy accepts it and rejects everything arriving over the network, and no credential is sent. Set it only when the classifier app authenticates callers with API keys.",
|
|
103
|
+
"examples": ["$env(CLASSIFIER_APP_API_KEY)"],
|
|
104
|
+
"x-advanced": true
|
|
105
|
+
},
|
|
106
|
+
"smartRoutingEnabled": {
|
|
107
|
+
"type": "boolean",
|
|
108
|
+
"title": "Smart Routing Enabled",
|
|
109
|
+
"description": "When true, apply model routing based on the models set in `modelsByComplexity` when confidence score meets the `minConfidenceForRouting` threshold. When set to false, classification still runs but model routing is not applied, useful for debugging or testing the classifier prompt.",
|
|
110
|
+
"default": true,
|
|
111
|
+
"x-advanced": true
|
|
112
|
+
},
|
|
111
113
|
"intents": {
|
|
112
114
|
"type": "array",
|
|
113
115
|
"title": "Intents",
|
|
@@ -134,7 +136,8 @@
|
|
|
134
136
|
]
|
|
135
137
|
}
|
|
136
138
|
}
|
|
137
|
-
}
|
|
139
|
+
},
|
|
140
|
+
"x-advanced": true
|
|
138
141
|
},
|
|
139
142
|
"classifierPrompt": {
|
|
140
143
|
"title": "Classifier Prompt",
|
|
@@ -151,7 +154,8 @@
|
|
|
151
154
|
"type": "string"
|
|
152
155
|
}
|
|
153
156
|
}
|
|
154
|
-
]
|
|
157
|
+
],
|
|
158
|
+
"x-advanced": true
|
|
155
159
|
},
|
|
156
160
|
"minConfidenceForRouting": {
|
|
157
161
|
"type": "number",
|
|
@@ -2,205 +2,112 @@
|
|
|
2
2
|
title: Programmable API
|
|
3
3
|
sidebar_label: Overview
|
|
4
4
|
description:
|
|
5
|
-
|
|
6
|
-
|
|
5
|
+
Find Zuplo runtime APIs for custom handlers and policies, including request
|
|
6
|
+
data, HTTP responses, caching, lifecycle hooks, logging, and service
|
|
7
|
+
authentication.
|
|
7
8
|
---
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
|
|
10
|
+
Use the Zuplo runtime APIs in your custom handlers and policies to work with
|
|
11
|
+
requests, responses, cached data, and gateway services. This index groups the
|
|
12
|
+
references by what you need to do.
|
|
11
13
|
|
|
12
|
-
|
|
14
|
+
<span id="core-requestresponse-apis" />
|
|
15
|
+
<span id="types-and-interfaces" />
|
|
13
16
|
|
|
14
|
-
|
|
17
|
+
## Requests and responses
|
|
15
18
|
|
|
16
|
-
|
|
17
|
-
- **Description**: Extended Request class with additional properties for
|
|
18
|
-
parameters, query, and user data
|
|
19
|
-
- **Key Features**: Type-safe parameters and query access, user authentication
|
|
20
|
-
data
|
|
19
|
+
These APIs provide request data, execution context, and response helpers:
|
|
21
20
|
|
|
22
|
-
|
|
21
|
+
| API | Purpose |
|
|
22
|
+
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
23
|
+
| <span id="zuplorequest" />[ZuploRequest](./zuplo-request.mdx) | Access request parameters, query values, and authenticated user data. |
|
|
24
|
+
| <span id="zuplocontext" />[ZuploContext](./zuplo-context.mdx) | Access the request ID, logger, route information, and event hooks. |
|
|
25
|
+
| <span id="requestuser" />[RequestUser](./request-user.mdx) | Represent the authenticated caller's identity and data. |
|
|
26
|
+
| <span id="httpproblems" />[HttpProblems](./http-problems.mdx) | Create HTTP problem responses. |
|
|
27
|
+
| <span id="httpstatuscode" />[HttpStatusCode](./http-problems.mdx) | Reference standard HTTP status codes. |
|
|
28
|
+
| <span id="problemresponseformatter" />[ProblemResponseFormatter](./problem-response-formatter.mdx) | Format HTTP problem details. |
|
|
29
|
+
| <span id="corspolicyconfiguration" />[CorsPolicyConfiguration](./custom-cors-policy.mdx) | Configure a custom CORS policy. |
|
|
23
30
|
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
- **Key Features**: Request ID, logging, route information, event hooks
|
|
31
|
+
<span id="caching-apis" />
|
|
32
|
+
<span id="data-management" />
|
|
27
33
|
|
|
28
|
-
|
|
34
|
+
## Caching and data
|
|
29
35
|
|
|
30
|
-
|
|
31
|
-
- **Description**: Utility class for generating RFC 7807 compliant problem
|
|
32
|
-
responses
|
|
33
|
-
- **Methods**: Static methods for all HTTP status codes (for example,
|
|
34
|
-
`badRequest`, `unauthorized`, `notFound`)
|
|
36
|
+
Choose an API for the data you need to store or load:
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
| API | Purpose |
|
|
39
|
+
| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
|
40
|
+
| <span id="zonecache" />[ZoneCache](./zone-cache.mdx) | Store key-value data within a zone. |
|
|
41
|
+
| <span id="memoryzonereadthroughcache" />[MemoryZoneReadThroughCache](./memory-zone-read-through-cache.mdx) | Cache values in memory with automatic loading. |
|
|
42
|
+
| <span id="streamingzonecache" />[StreamingZoneCache](./streaming-zone-cache.mdx) | Cache streaming responses. |
|
|
43
|
+
| <span id="contextdata" /><span id="contextdata-1" />[ContextData](./context-data.mdx) | Store typed context data. |
|
|
44
|
+
| <span id="backgroundloader" />[BackgroundLoader](./background-loader.mdx) | Load and cache data in the background. |
|
|
45
|
+
| <span id="backgrounddispatcher" />[BackgroundDispatcher](./background-dispatcher.mdx) | Enqueue work for batch processing in the background. |
|
|
37
46
|
|
|
38
|
-
-
|
|
39
|
-
-
|
|
47
|
+
<span id="runtime-extensions" />
|
|
48
|
+
<span id="hooks-and-events" />
|
|
40
49
|
|
|
41
|
-
|
|
50
|
+
## Runtime extensions and hooks
|
|
42
51
|
|
|
43
|
-
|
|
44
|
-
([ProblemResponseFormatter](./problem-response-formatter.mdx))
|
|
45
|
-
- **Description**: Utility class for formatting RFC 7807 compliant problem
|
|
46
|
-
responses
|
|
47
|
-
- **Methods**: `format` - Formats problem details into standard responses
|
|
52
|
+
These APIs extend runtime behavior and handle errors:
|
|
48
53
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
- `awsLambdaHandler` - [AWS Lambda Handler](/docs/handlers/aws-lambda)
|
|
57
|
-
- `mcpServerHandler` - [MCP Server Handler](/docs/handlers/mcp-server)
|
|
58
|
-
- `openApiSpecHandler` - [OpenAPI Spec Handler](/docs/handlers/openapi)
|
|
59
|
-
- `redirectHandler` - [Redirect Handler](/docs/handlers/redirect)
|
|
60
|
-
- `urlForwardHandler` - [URL Forward Handler](/docs/handlers/url-forward)
|
|
61
|
-
- `urlRewriteHandler` - [URL Rewrite Handler](/docs/handlers/url-rewrite)
|
|
62
|
-
- `webSocketHandler` - [WebSocket Handler](/docs/handlers/websocket-handler)
|
|
63
|
-
- Custom handlers - [Function Handler](/docs/handlers/custom-handler)
|
|
64
|
-
|
|
65
|
-
## Caching APIs
|
|
66
|
-
|
|
67
|
-
### ZoneCache
|
|
68
|
-
|
|
69
|
-
- **Status**: Documented ([Zone Cache](./zone-cache.mdx))
|
|
70
|
-
- **Description**: Key-value cache with zone-level storage
|
|
71
|
-
- **Key Methods**: `get`, `put`, `delete`
|
|
72
|
-
|
|
73
|
-
### MemoryZoneReadThroughCache
|
|
74
|
-
|
|
75
|
-
- **Status**: Documented
|
|
76
|
-
([Memory Zone Read Through Cache](./memory-zone-read-through-cache.mdx))
|
|
77
|
-
- **Description**: In-memory cache with automatic loading
|
|
78
|
-
- **Key Methods**: `get`, `put`
|
|
79
|
-
|
|
80
|
-
### StreamingZoneCache
|
|
81
|
-
|
|
82
|
-
- **Status**: Documented ([Streaming Zone Cache](./streaming-zone-cache.mdx))
|
|
83
|
-
- **Description**: Cache for streaming responses
|
|
84
|
-
- **Key Methods**: `get`, `put`, `delete`
|
|
85
|
-
|
|
86
|
-
## Data Management
|
|
54
|
+
| API | Purpose |
|
|
55
|
+
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
|
56
|
+
| <span id="runtimeextensions" />[RuntimeExtensions](./runtime-extensions.mdx) | Register plugins, request and response hooks, and custom error handling. |
|
|
57
|
+
| <span id="zuplocontexthooks" />[Request/response hooks](./hooks.mdx) | Run code at request and response lifecycle events. |
|
|
58
|
+
| <span id="runtimeerror" />[RuntimeError](./runtime-errors.mdx) | Represent a runtime error. |
|
|
59
|
+
| <span id="configurationerror" />[ConfigurationError](./runtime-errors.mdx) | Represent a configuration error. |
|
|
87
60
|
|
|
88
|
-
|
|
61
|
+
<span id="utility-apis" />
|
|
89
62
|
|
|
90
|
-
|
|
91
|
-
- **Description**: Type-safe context data storage
|
|
92
|
-
- **Key Methods**: `get`, `set`
|
|
63
|
+
## Environment and services
|
|
93
64
|
|
|
94
|
-
|
|
65
|
+
These APIs provide environment values, logging, and platform services:
|
|
95
66
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
67
|
+
| API | Purpose |
|
|
68
|
+
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
69
|
+
| <span id="environment" />[environment](./environment.mdx) | Read environment variables. |
|
|
70
|
+
| <span id="logger" />[Logger](./logger.mdx) | Write structured log messages. |
|
|
71
|
+
| <span id="zuploservices" />[ZuploServices](./zuplo-id-token.mdx) | Create identity tokens with `getIDToken` to authenticate gateway requests to external services. |
|
|
99
72
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
- **Status**: Documented ([Background Dispatcher](./background-dispatcher.mdx))
|
|
103
|
-
- **Description**: Batch processing for background tasks
|
|
104
|
-
- **Key Methods**: `enqueue`
|
|
105
|
-
|
|
106
|
-
## Runtime Extensions
|
|
107
|
-
|
|
108
|
-
### RuntimeExtensions
|
|
109
|
-
|
|
110
|
-
- **Status**: Documented ([Runtime Extensions](./runtime-extensions.mdx))
|
|
111
|
-
- **Description**: API for extending runtime behavior
|
|
112
|
-
- **Key Features**: Plugin support, request/response hooks, custom error
|
|
113
|
-
handling
|
|
114
|
-
|
|
115
|
-
### RuntimeError
|
|
73
|
+
## Handlers
|
|
116
74
|
|
|
117
|
-
-
|
|
118
|
-
- **Description**: Base error class for runtime errors
|
|
75
|
+
<span id="available-handlers" />
|
|
119
76
|
|
|
120
|
-
|
|
77
|
+
A route's handler determines how the gateway responds to a request:
|
|
121
78
|
|
|
122
|
-
|
|
123
|
-
|
|
79
|
+
| Handler | Purpose |
|
|
80
|
+
| ------------------------------------------------------- | --------------------------------------- |
|
|
81
|
+
| [`awsLambdaHandler`](../handlers/aws-lambda.mdx) | Invoke an AWS Lambda function. |
|
|
82
|
+
| [`mcpServerHandler`](../handlers/mcp-server.mdx) | Expose API operations through MCP. |
|
|
83
|
+
| [`openApiSpecHandler`](../handlers/openapi.mdx) | Serve an OpenAPI specification. |
|
|
84
|
+
| [`redirectHandler`](../handlers/redirect.mdx) | Return a redirect response. |
|
|
85
|
+
| [`urlForwardHandler`](../handlers/url-forward.mdx) | Forward requests to a backend. |
|
|
86
|
+
| [`urlRewriteHandler`](../handlers/url-rewrite.mdx) | Rewrite the URL used to call a backend. |
|
|
87
|
+
| [`webSocketHandler`](../handlers/websocket-handler.mdx) | Handle WebSocket connections. |
|
|
88
|
+
| [Custom function](../handlers/custom-handler.mdx) | Implement a handler in your own code. |
|
|
124
89
|
|
|
125
90
|
## Plugins
|
|
126
91
|
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
- `
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
- `
|
|
149
|
-
- `NewRelicMetricsPlugin` - New Relic metrics
|
|
150
|
-
|
|
151
|
-
### Storage Plugins
|
|
152
|
-
|
|
153
|
-
- `AzureBlobPlugin` - Azure Blob Storage integration
|
|
154
|
-
- `AzureEventHubsRequestLoggerPlugin` - Azure Event Hubs logging
|
|
155
|
-
- `HydrolixRequestLoggerPlugin` - Hydrolix data platform integration
|
|
156
|
-
|
|
157
|
-
### Special Plugins
|
|
158
|
-
|
|
159
|
-
- `AkamaiApiSecurityPlugin` - Akamai API security integration
|
|
160
|
-
- `StripeMonetizationPlugin` - Stripe billing integration
|
|
161
|
-
|
|
162
|
-
## Utility APIs
|
|
163
|
-
|
|
164
|
-
### environment
|
|
165
|
-
|
|
166
|
-
- **Status**: Documented ([Environment Variables](./environment.mdx))
|
|
167
|
-
- **Description**: Access to environment variables
|
|
168
|
-
|
|
169
|
-
### ZuploServices
|
|
170
|
-
|
|
171
|
-
- **Status**: Documented ([Zuplo ID Token](./zuplo-id-token.mdx))
|
|
172
|
-
- **Description**: Zuplo platform services
|
|
173
|
-
|
|
174
|
-
## Types and Interfaces
|
|
175
|
-
|
|
176
|
-
### RequestUser
|
|
177
|
-
|
|
178
|
-
- **Status**: Documented ([Request User](./request-user.mdx))
|
|
179
|
-
- **Description**: User data structure for authenticated requests
|
|
180
|
-
|
|
181
|
-
### Logger
|
|
182
|
-
|
|
183
|
-
- **Status**: Documented ([Logger](./logger.mdx))
|
|
184
|
-
- **Description**: Structured logging interface
|
|
185
|
-
|
|
186
|
-
### ContextData
|
|
187
|
-
|
|
188
|
-
- **Status**: Documented ([Context Data](./context-data.mdx))
|
|
189
|
-
- **Description**: Type-safe context data storage
|
|
190
|
-
|
|
191
|
-
### CorsPolicyConfiguration
|
|
192
|
-
|
|
193
|
-
- **Status**: Documented ([Custom CORS Policy](./custom-cors-policy.mdx))
|
|
194
|
-
- **Description**: CORS policy configuration
|
|
195
|
-
|
|
196
|
-
## Hooks and Events
|
|
197
|
-
|
|
198
|
-
### ZuploContextHooks
|
|
199
|
-
|
|
200
|
-
- **Status**: Documented ([Hooks](./hooks.mdx))
|
|
201
|
-
- **Description**: Request/response lifecycle hooks
|
|
202
|
-
|
|
203
|
-
---
|
|
204
|
-
|
|
205
|
-
This index provides an overview of the runtime APIs available in Zuplo. For
|
|
206
|
-
detailed information about each API, follow the documentation links provided.
|
|
92
|
+
For setup instructions, see the [logging](../articles/logging.mdx) and
|
|
93
|
+
[metrics](../articles/metrics-plugins.mdx) guides. These integrations are also
|
|
94
|
+
available through runtime plugins:
|
|
95
|
+
|
|
96
|
+
| Plugin | Integration |
|
|
97
|
+
| ------------------------------------------------------ | -------------------------- |
|
|
98
|
+
| <span id="logging-plugins" />`AWSLoggingPlugin` | AWS CloudWatch logging |
|
|
99
|
+
| `DataDogLoggingPlugin` | Datadog logging |
|
|
100
|
+
| `DynaTraceLoggingPlugin` | Dynatrace logging |
|
|
101
|
+
| `GoogleCloudLoggingPlugin` | Google Cloud Logging |
|
|
102
|
+
| `LokiLoggingPlugin` | Grafana Loki logging |
|
|
103
|
+
| `NewRelicLoggingPlugin` | New Relic logging |
|
|
104
|
+
| `SplunkLoggingPlugin` | Splunk logging |
|
|
105
|
+
| `SumoLogicLoggingPlugin` | Sumo Logic logging |
|
|
106
|
+
| `VMWareLogInsightLoggingPlugin` | VMware Log Insight logging |
|
|
107
|
+
| <span id="metrics-plugins" />`DataDogMetricsPlugin` | Datadog metrics |
|
|
108
|
+
| `DynatraceMetricsPlugin` | Dynatrace metrics |
|
|
109
|
+
| `NewRelicMetricsPlugin` | New Relic metrics |
|
|
110
|
+
| <span id="storage-plugins" />`AzureBlobPlugin` | Azure Blob Storage |
|
|
111
|
+
| `AzureEventHubsRequestLoggerPlugin` | Azure Event Hubs logging |
|
|
112
|
+
| `HydrolixRequestLoggerPlugin` | Hydrolix |
|
|
113
|
+
| <span id="special-plugins" />`AkamaiApiSecurityPlugin` | Akamai API security |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "zuplo",
|
|
3
|
-
"version": "7.8.
|
|
3
|
+
"version": "7.8.14",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "The official Zuplo CLI for local development and platform management",
|
|
6
6
|
"homepage": "https://zuplo.com/docs/cli/overview",
|
|
@@ -32,9 +32,9 @@
|
|
|
32
32
|
"zuplo": "zuplo.js"
|
|
33
33
|
},
|
|
34
34
|
"dependencies": {
|
|
35
|
-
"@zuplo/cli": "7.8.
|
|
36
|
-
"@zuplo/core": "7.8.
|
|
37
|
-
"@zuplo/runtime": "7.8.
|
|
38
|
-
"@zuplo/test": "7.8.
|
|
35
|
+
"@zuplo/cli": "7.8.14",
|
|
36
|
+
"@zuplo/core": "7.8.14",
|
|
37
|
+
"@zuplo/runtime": "7.8.14",
|
|
38
|
+
"@zuplo/test": "7.8.14"
|
|
39
39
|
}
|
|
40
40
|
}
|