You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a request-for-comment regarding the ability to customize the HTTP API exposed by Celest Functions.
In cases where Celest's standard HTTP conventions do not align with your requirements, you can control the HTTP API generated for your Celest Functions using the HTTP annotations.
Execution Controls
The @http and @httpError annotations allow you to control the behavior of the HTTP endpoint, such as how the endpoint is exposed, and how it responds in both success and error cases.
@http
To configure the method and default status code of your HTTP endpoint, use the @http annotation.
To control the status code returned from one or more thrown types, use the @httpError annotation.
@httpError(403, UnauthorizedException)
@httpError(404, BadNameException, NotFoundException)
Future<String> greet(String name) async {
if (name.isEmpty) {
throwBadNameException();
}
if (!name.startsWith('C')) {
throwNotFoundException();
}
if (name !='Celest') {
throwUnauthorizedException();
}
return'Hello, $name';
}
Exception types are handled in order of specificity. Specifying a type that other types inherit from or implement will only apply the status code to subtypes which are not already covered by a more specific case.
For example, the following will return a 404 status code for both the concrete NotFoundException type and BadNameException (since it is a subtype of Exception), but not UnauthorizedException which is covered by a more specific control.
The @httpHeader and @httpQuery annotations allow you to map input parameters to HTTP headers and query parameters, respectively.
Any parameters which are not targeted by these annotations are passed as the request body.
Note
Some combinations are disallowed. For example, if the @http annotation specifies a GET method, then all input
parameters must be mapped, or there must be no input parameters, such that the request body is empty.
@httpHeader
To map an input parameter to an HTTP header, use the @httpHeader annotation.
Note
Only parameters of type String, int, double, bool, DateTime, or a List of these types, can be targeted by @httpHeader.
Feedback still welcome - V1 has now been released and we'll continue to explore the features necessary to give you the right level of customization building Celest backends 💪
This is a request-for-comment regarding the ability to customize the HTTP API exposed by Celest Functions.
In cases where Celest's standard HTTP conventions do not align with your requirements, you can control the HTTP API generated for your Celest Functions using the HTTP annotations.
Execution Controls
The
@http
and@httpError
annotations allow you to control the behavior of the HTTP endpoint, such as how the endpoint is exposed, and how it responds in both success and error cases.@http
To configure the method and default status code of your HTTP endpoint, use the
@http
annotation.No changes are made to the generated client interface, only its execution.
@httpError
To control the status code returned from one or more thrown types, use the
@httpError
annotation.Exception types are handled in order of specificity. Specifying a type that other types inherit from or implement will only apply the status code to subtypes which are not already covered by a more specific case.
For example, the following will return a 404 status code for both the concrete
NotFoundException
type andBadNameException
(since it is a subtype ofException
), but notUnauthorizedException
which is covered by a more specific control.Request Controls
The
@httpHeader
and@httpQuery
annotations allow you to map input parameters to HTTP headers and query parameters, respectively.Any parameters which are not targeted by these annotations are passed as the request body.
Note
Some combinations are disallowed. For example, if the
@http
annotation specifies aGET
method, then all inputparameters must be mapped, or there must be no input parameters, such that the request body is empty.
@httpHeader
To map an input parameter to an HTTP header, use the
@httpHeader
annotation.Note
Only parameters of type
String
,int
,double
,bool
,DateTime
, or aList
of these types, can be targeted by@httpHeader
.In the generated client, these parameters are passed transparently as function arguments.
The following HTTP headers are reserved and cannot be targeted by
@httpHeader
:Connection
Content-Length
Expect
Host
Max-Forwards
Server
TE
Trailer
Transfer-Encoding
Upgrade
User-Agent
Via
X-Forwarded-For
@httpQuery
To map an input parameter to a query parameter, use the
@httpQuery
annotation.Note
Only parameters of type
String
,int
,double
,bool
,DateTime
, or aList
of these types, can be targeted by@httpQuery
.In the generated client, these parameters are passed transparently as function arguments.
The text was updated successfully, but these errors were encountered: