proposal: v2 gateway/provider API spec #1804
Draft
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This is a proposal for a new standardized v2 API.
The new spec includes the following changes from v1:
* the API paths now include a version prefix, `/v2`. The goal is to
allow a compatabiliy period where both APIs are deployed.
* the path structures try to emphasize a nested REST-ful struture.
Specifically, the `logs` and `scale` endpoints are now sub-paths of
the function
* Reference to service are now replaced with Function, request and
response objects, fields, and parameters should always use `function`
and not `service`. The one exception is the PrometheusAlertRequest
object, where we can not control this schema.
* There should only be one path for each action. For example
creating a function is now a `PUT` on `system/functions/{functionName}` instead of
supporting both `POST` on `/system/functions` and `PUT` on the named path.
* To bring consistency between the invoke and system endpoints, the
`name` parameters are defined as a regex pattern with an optional
`.namespace` suffix. Specifically, to create a function `echo` in the default
namespace you `PUT` to `system/functions/echo`. To create the `echo`
function in the `internal` namespace, you would use
`system/functions/echo.internal`. Both functions and secrets support
this pattern now.
To ensure consistency, there is a `NamespacedNameParameter` object in
the spec. It defines the following regexp pattern using named groups.
```
^(?<name>[a-zA-Z][a-zA-Z0-9-_]*)(.(?<namespace>[a-zA-Z][a-zA-Z0-9-_]*)?)$
```
This is valid for the OpenAPI spec, but the named groups might not be
supported in _all_ languages. If we want to support code generation,
we should consider removing the named groups, this is the equivalent
pattern
```
^([a-zA-Z][a-zA-Z0-9-_]*)(.[a-zA-Z][a-zA-Z0-9-_]*)?$
```
* Note that the list endpoints still support a `GET` query parameter
for `namespace`.
Signed-off-by: Lucas Roesler <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a proposal for a new standardized v2 API.
The new spec includes the following changes from v1:
the API paths now include a version prefix,
/v2. The goal is to allow a compatabiliy period where both APIs are deployed.the path structures try to emphasize a nested REST-ful struture. Specifically, the
logsandscaleendpoints are now sub-paths of the functionReference to service are now replaced with Function, request and response objects, fields, and parameters should always use
functionand notservice. The one exception is the PrometheusAlertRequest object, where we can not control this schema.There should only be one path for each action. For example creating a function is now a
PUTonsystem/functions/{functionName}instead of supporting bothPOSTon/system/functionsandPUTon the named path.To bring consistency between the invoke and system endpoints, the
nameparameters are defined as a regex pattern with an optional.namespacesuffix. Specifically, to create a functionechoin the default namespace youPUTtosystem/functions/echo. To create theechofunction in theinternalnamespace, you would usesystem/functions/echo.internal. Both functions and secrets support this pattern now.To ensure consistency, there is a
NamespacedNameParameterobject in the spec. It defines the following regexp pattern using named groups.^(?<name>[a-zA-Z][a-zA-Z0-9-_]*)(.(?<namespace>[a-zA-Z][a-zA-Z0-9-_]*)?)$This is valid for the OpenAPI spec, but the named groups might not be supported in all languages. If we want to support code generation, we should consider removing the named groups, this is the equivalent pattern^([a-zA-Z][a-zA-Z0-9-_]*)(.[a-zA-Z][a-zA-Z0-9-_]*)?$GETquery parameter fornamespace.Motivation and Context
design/approvedlabelThis was discussed several times in community calls, so I am posting this here so that some kind of consensus can be made. A PR allows comments on specific lines, which is much easier to follow vs an issue.
How Has This Been Tested?
NA
Types of changes
Checklist:
git commit -s