@typespec/http
Advanced tools
TypeSpec HTTP protocol binding
npm install @typespec/http
Add the following in tspconfig.yaml:
linter:
extends:
- "@typespec/http/all"
Available ruleSets:
@typespec/http/all| Name | Description |
|---|---|
@typespec/http/op-reference-container-route | Check for referenced (op is) operations which have a @route on one of their containers. |
@body@bodyIgnore@bodyRoot@delete@get@head@header@includeInapplicableMetadataInPayload@multipartBody@patch@path@post@put@query@route@server@sharedRoute@statusCode@useAuth@bodyExplicitly specify that this property type will be exactly the HTTP body.
This means that any properties under @body cannot be marked as headers, query parameters, or path parameters.
If wanting to change the resolution of the body but still mix parameters, use @bodyRoot.
@TypeSpec.Http.body
ModelProperty
None
op upload(@body image: bytes): void;
op download(): {
@body image: bytes;
};
@bodyIgnoreSpecify that this property shouldn't be included in the HTTP body. This can be useful when bundling metadata together that would result in an empty property to be included in the body.
@TypeSpec.Http.bodyIgnore
ModelProperty
None
op upload(
name: string,
@bodyIgnore headers: {
@header id: string;
},
): void;
@bodyRootSpecify that the body resolution should be resolved from that property. By default the body is resolved by including all properties in the operation request/response that are not metadata. This allows to nest the body in a property while still allowing to use headers, query parameters, and path parameters in the same model.
@TypeSpec.Http.bodyRoot
ModelProperty
None
op upload(
@bodyRoot user: {
name: string;
@header id: string;
},
): void;
op download(): {
@bodyRoot user: {
name: string;
@header id: string;
};
};
@deleteSpecify the HTTP verb for the target operation to be DELETE.
@TypeSpec.Http.delete
Operation
None
@delete op set(petId: string): void;
@getSpecify the HTTP verb for the target operation to be GET.
@TypeSpec.Http.get
Operation
None
@get op read(): string;
@headSpecify the HTTP verb for the target operation to be HEAD.
@TypeSpec.Http.head
Operation
None
@head op ping(petId: string): void;
@headerSpecify 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
@includeInapplicableMetadataInPayloadSpecify 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. |
@multipartBody@TypeSpec.Http.multipartBody
ModelProperty
None
op upload(
@header `content-type`: "multipart/form-data",
@multipartBody body: {
fullName: HttpPart<string>;
headShots: HttpPart<Image>[];
},
): void;
@patchSpecify the HTTP verb for the target operation to be PATCH.
@TypeSpec.Http.patch
Operation
None
@patch op update(pet: Pet): void;
@pathExplicitly specify that this property is to be interpolated as a path parameter.
@TypeSpec.Http.path(paramNameOrOptions?: valueof string | TypeSpec.Http.PathOptions)
ModelProperty
| Name | Type | Description |
|---|---|---|
| paramNameOrOptions | valueof string | TypeSpec.Http.PathOptions | Optional name of the parameter in the uri template or options. |
@route("/read/{explicit}/things/{implicit}")
op read(@path explicit: string, implicit: string): void;
@postSpecify the HTTP verb for the target operation to be POST.
@TypeSpec.Http.post
Operation
None
@post op create(pet: Pet): void;
@putSpecify the HTTP verb for the target operation to be PUT.
@TypeSpec.Http.put
Operation
None
@put op set(pet: Pet): void;
@querySpecify this property is to be sent as a query parameter.
@TypeSpec.Http.query(queryNameOrOptions?: valueof string | TypeSpec.Http.QueryOptions)
ModelProperty
| Name | Type | Description |
|---|---|---|
| queryNameOrOptions | valueof 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", explode: true }) ids: string[]): void;
@routeDefines the relative route URI template for the target operation as defined by RFC 6570
@route can only be applied to operations, namespaces, and interfaces.
@TypeSpec.Http.route(path: valueof string, options?: { shared: boolean })
Namespace | Interface | Operation
| Name | Type | Description |
|---|---|---|
| path | valueof string | |
| options | {...} | DEPRECATED Set of parameters used to configure the route. Supports {shared: true} which indicates that the route may be shared by several operations. |
@route("/widgets/{id}") op getWidget(@path id: string): Widget;
@route("/files{+path}") op getFile(@path path: string): bytes;
@route("/files") op list(select?: string, filter?: string): Files[];
@route("/files{?select,filter}") op listFullUriTemplate(select?: string, filter?: string): Files[];
@serverSpecify an endpoint for this service. Multiple @server decorators can be used to specify multiple endpoints.
@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",
})
@service
@server("https://example.com", "Standard endpoint")
@server(
"https://{project}.private.example.com",
"Private project endpoint",
{
project: string,
}
)
namespace PetStore;
@sharedRoute@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
@statusCodeSpecify 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;
};
@useAuthSpecify 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;
FAQs
TypeSpec HTTP protocol binding
The npm package @typespec/http receives a total of 55,818 weekly downloads. As such, @typespec/http popularity was classified as popular.
We found that @typespec/http demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.