TypeSpec HTTP protocol binding
npm install @typespec/httpAdd the following in tspconfig.yaml:
linter:
extends:
- "@typespec/http/all"Available ruleSets:
| Name | Description |
|---|---|
@typespec/http/op-reference-container-route |
Check for referenced (op is) operations which have a @route on one of their containers. |
@body@delete@get@head@header@includeInapplicableMetadataInPayload@patch@path@post@put@query@route@server@sharedRoute@statusCode@useAuth
Explicitly specify that this property is to be set as the body
@TypeSpec.Http.body
ModelProperty
None
op upload(@body image: bytes): void;
op download(): {
@body image: bytes;
};
Specify the HTTP verb for the target operation to be DELETE.
@TypeSpec.Http.delete
Operation
None
@delete op set(petId: string): void;
Specify the HTTP verb for the target operation to be GET.
@TypeSpec.Http.get
Operation
None
@get op read(): string;
Specify the HTTP verb for the target operation to be HEAD.
@TypeSpec.Http.head
Operation
None
@head op ping(petId: string): void;
Specify this property is to be sent or received as an HTTP header.
@TypeSpec.Http.header(headerNameOrOptions?: string | TypeSpec.Http.HeaderOptions)
ModelProperty
| Name | Type | Description |
|---|---|---|
| headerNameOrOptions | string | TypeSpec.Http.HeaderOptions |
Optional name of the header when sent over HTTP or header options. By default the header name will be the property name converted from camelCase to kebab-case. (e.g. contentType -> content-type) |
op read(@header accept: string): {
@header("ETag") eTag: string;
};
op create(
@header({
name: "X-Color",
format: "csv",
})
colors: string[],
): void;
op read(): {
@header contentType: string;
}; // headerName: content-type
op update(@header ifMatch: string): void; // headerName: if-match
Specify if inapplicable metadata should be included in the payload for the given entity.
@TypeSpec.Http.includeInapplicableMetadataInPayload(value: valueof boolean)
unknown
| Name | Type | Description |
|---|---|---|
| value | valueof boolean |
If true, inapplicable metadata will be included in the payload. |
Specify the HTTP verb for the target operation to be PATCH.
@TypeSpec.Http.patch
Operation
None
@patch op update(pet: Pet): void;
Explicitly specify that this property is to be interpolated as a path parameter.
@TypeSpec.Http.path(paramName?: valueof string)
ModelProperty
| Name | Type | Description |
|---|---|---|
| paramName | valueof string |
Optional name of the parameter in the url template. |
@route("/read/{explicit}/things/{implicit}")
op read(@path explicit: string, implicit: string): void;
Specify the HTTP verb for the target operation to be POST.
@TypeSpec.Http.post
Operation
None
@post op create(pet: Pet): void;
Specify the HTTP verb for the target operation to be PUT.
@TypeSpec.Http.put
Operation
None
@put op set(pet: Pet): void;
Specify this property is to be sent as a query parameter.
@TypeSpec.Http.query(queryNameOrOptions?: string | TypeSpec.Http.QueryOptions)
ModelProperty
| Name | Type | Description |
|---|---|---|
| queryNameOrOptions | string | TypeSpec.Http.QueryOptions |
Optional name of the query when included in the url or query parameter options. |
op read(@query select: string, @query("order-by") orderBy: string): void;
op list(
@query({
name: "id",
format: "multi",
})
ids: string[],
): void;
Defines the relative route URI for the target operation
The first argument should be a URI fragment that may contain one or more path parameter fields.
If the namespace or interface that contains the operation is also marked with a @route decorator,
it will be used as a prefix to the route URI of the operation.
@route can only be applied to operations, namespaces, and interfaces.
@TypeSpec.Http.route(path: valueof string, options?: (anonymous model))
Namespace | Interface | Operation
| Name | Type | Description |
|---|---|---|
| path | valueof string |
Relative route path. Cannot include query parameters. |
| options | {...} |
Set of parameters used to configure the route. Supports {shared: true} which indicates that the route may be shared by several operations. |
@route("/widgets")
op getWidget(@path id: string): Widget;
Specify the endpoint for this service.
@TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record<unknown>)
Namespace
| Name | Type | Description |
|---|---|---|
| url | valueof string |
Server endpoint |
| description | valueof string |
Description of the endpoint |
| parameters | Record<unknown> |
Optional set of parameters used to interpolate the url. |
@service
@server("https://example.com", "Single server endpoint")
namespace PetStore;
@server("https://{region}.foo.com", "Regional endpoint", {
@doc("Region name")
region?: string = "westus",
})
@sharedRoute marks the operation as sharing a route path with other operations.
When an operation is marked with @sharedRoute, it enables other operations to share the same
route path as long as those operations are also marked with @sharedRoute.
@sharedRoute can only be applied directly to operations.
@sharedRoute
@route("/widgets")
op getWidget(@path id: string): Widget;
@TypeSpec.Http.sharedRoute
Operation
None
Specify the status code for this response. Property type must be a status code integer or a union of status code integer.
@TypeSpec.Http.statusCode
ModelProperty
None
op read(): {@statusCode: 200, @body pet: Pet}
op create(): {@statusCode: 201 | 202}
Specify authentication for a whole service or specific methods. See the documentation in the Http library for full details.
@TypeSpec.Http.useAuth(auth: {} | Union | {}[])
Namespace | Interface | Operation
| Name | Type | Description |
|---|---|---|
| auth | {} | Union | {}[] |
Authentication configuration. Can be a single security scheme, a union(either option is valid authentication) or a tuple (must use all authentication together) |
@service
@useAuth(BasicAuth)
namespace PetStore;