@typespec/http

TypeSpec HTTP protocol binding

Install

npm install @typespec/http

Linter

Usage

Add the following in tspconfig.yaml:

linter:
  extends:
    - "@typespec/http/all"

RuleSets

Available ruleSets:

• @typespec/http/all

Rules

Name	Description
@typespec/http/op-reference-container-route	Check for referenced (op is) operations which have a @route on one of their containers.

Decorators

TypeSpec.Http

• @body
• @delete
• @get
• @head
• @header
• @includeInapplicableMetadataInPayload
• @patch
• @path
• @post
• @put
• @query
• @route
• @server
• @sharedRoute
• @statusCode
• @useAuth

@body

Explicitly specify that this property is to be set as the body

@TypeSpec.Http.body

Target

ModelProperty

Parameters

None

Examples

op upload(@body image: bytes): void;
op download(): {
  @body image: bytes;
};

@delete

Specify the HTTP verb for the target operation to be DELETE.

@TypeSpec.Http.delete

Target

Operation

Parameters

None

Examples

@delete op set(petId: string): void;

@get

Specify the HTTP verb for the target operation to be GET.

@TypeSpec.Http.get

Target

Operation

Parameters

None

Examples

@get op read(): string;

@head

Specify the HTTP verb for the target operation to be HEAD.

@TypeSpec.Http.head

Target

Operation

Parameters

None

Examples

@head op ping(petId: string): void;

@header

Specify this property is to be sent or received as an HTTP header.

@TypeSpec.Http.header(headerNameOrOptions?: string | TypeSpec.Http.HeaderOptions)

Target

ModelProperty

Parameters

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)

Examples

op read(@header accept: string): {
  @header("ETag") eTag: string;
};
op create(
  @header({
    name: "X-Color",
    format: "csv",
  })
  colors: string[],
): void;

Implicit header name

op read(): {
  @header contentType: string;
}; // headerName: content-type
op update(@header ifMatch: string): void; // headerName: if-match

@includeInapplicableMetadataInPayload

Specify if inapplicable metadata should be included in the payload for the given entity.

@TypeSpec.Http.includeInapplicableMetadataInPayload(value: valueof boolean)

Target

unknown

Parameters

Name	Type	Description
value	valueof boolean	If true, inapplicable metadata will be included in the payload.

@patch

Specify the HTTP verb for the target operation to be PATCH.

@TypeSpec.Http.patch

Target

Operation

Parameters

None

Examples

@patch op update(pet: Pet): void;

@path

Explicitly specify that this property is to be interpolated as a path parameter.

@TypeSpec.Http.path(paramName?: valueof string)

Target

ModelProperty

Parameters

Name	Type	Description
paramName	valueof string	Optional name of the parameter in the url template.

Examples

@route("/read/{explicit}/things/{implicit}")
op read(@path explicit: string, implicit: string): void;

@post

Specify the HTTP verb for the target operation to be POST.

@TypeSpec.Http.post

Target

Operation

Parameters

None

Examples

@post op create(pet: Pet): void;

@put

Specify the HTTP verb for the target operation to be PUT.

@TypeSpec.Http.put

Target

Operation

Parameters

None

Examples

@put op set(pet: Pet): void;

@query

Specify this property is to be sent as a query parameter.

@TypeSpec.Http.query(queryNameOrOptions?: string | TypeSpec.Http.QueryOptions)

Target

ModelProperty

Parameters

Name	Type	Description
queryNameOrOptions	string | TypeSpec.Http.QueryOptions	Optional name of the query when included in the url or query parameter options.

Examples

op read(@query select: string, @query("order-by") orderBy: string): void;
op list(
  @query({
    name: "id",
    format: "multi",
  })
  ids: string[],
): void;

@route

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))

Target

Namespace | Interface | Operation

Parameters

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.

Examples

@route("/widgets")
op getWidget(@path id: string): Widget;

@server

Specify the endpoint for this service.

@TypeSpec.Http.server(url: valueof string, description: valueof string, parameters?: Record<unknown>)

Target

Namespace

Parameters

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.

Examples

@service
@server("https://example.com", "Single server endpoint")
namespace PetStore;

parameterized

@server("https://{region}.foo.com", "Regional endpoint", {
@doc("Region name")
region?: string = "westus",
})

@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

Target

Operation

Parameters

None

@statusCode

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

Target

ModelProperty

Parameters

None

Examples

op read(): {@statusCode: 200, @body pet: Pet}
op create(): {@statusCode: 201 | 202}

@useAuth

Specify authentication for a whole service or specific methods. See the documentation in the Http library for full details.

@TypeSpec.Http.useAuth(auth: {} | Union | {}[])

Target

Namespace | Interface | Operation

Parameters

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)

Examples

@service
@useAuth(BasicAuth)
namespace PetStore;