Skip to content

Decorators

TypeSpec.Http

@body

Explicitly 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

Target

ModelProperty

Parameters

None

Examples

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

@bodyIgnore

Specify 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

Target

ModelProperty

Parameters

None

Examples

op upload(
  name: string,
  @bodyIgnore headers: {
    @header id: string;
  },
): void;

@bodyRoot

Specify 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

Target

ModelProperty

Parameters

None

Examples

op upload(
  @bodyRoot user: {
    name: string;
    @header id: string;
  },
): void;
op download(): {
  @bodyRoot user: {
    name: string;
    @header id: string;
  };
};

@cookie

Specify this property is to be sent or received in the cookie.

@TypeSpec.Http.cookie(cookieNameOrOptions?: valueof string | TypeSpec.Http.CookieOptions)

Target

ModelProperty

Parameters

NameTypeDescription
cookieNameOrOptionsvalueof string | TypeSpec.Http.CookieOptionsOptional name of the cookie in the cookie or cookie options.
By default the cookie name will be the property name converted from camelCase to snake_case. (e.g. authToken -> auth_token)

Examples

op read(@cookie token: string): {
  data: string[];
};
op create(
  @cookie({
    name: "auth_token",
  })
  data: string[],
): void;
Implicit header name
op read(): {
  @cookie authToken: string;
}; // headerName: auth_token
op update(@cookie AuthToken: string): void; // headerName: auth_token

@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?: valueof string | TypeSpec.Http.HeaderOptions)

Target

ModelProperty

Parameters

NameTypeDescription
headerNameOrOptionsvalueof string | TypeSpec.Http.HeaderOptionsOptional 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

@multipartBody

@TypeSpec.Http.multipartBody

Target

ModelProperty

Parameters

None

Examples

op upload(
  @header `content-type`: "multipart/form-data",
  @multipartBody body: {
    fullName: HttpPart<string>;
    headShots: HttpPart<Image>[];
  },
): void;

@patch

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

@TypeSpec.Http.patch(options?: valueof TypeSpec.Http.PatchOptions)

Target

Operation

Parameters

NameTypeDescription
optionsvalueof PatchOptionsOptions for the PATCH operation.

Examples

@patch op update(pet: Pet): void;
// Disable implicit optionality, making the body of the PATCH operation use the
// optionality as defined in the `Pet` model.
@patch(#{ implicitOptionality: false })
op update(pet: Pet): void;

@path

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

@TypeSpec.Http.path(paramNameOrOptions?: valueof string | TypeSpec.Http.PathOptions)

Target

ModelProperty

Parameters

NameTypeDescription
paramNameOrOptionsvalueof string | TypeSpec.Http.PathOptionsOptional name of the parameter in the uri template or options.

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?: valueof string | TypeSpec.Http.QueryOptions)

Target

ModelProperty

Parameters

NameTypeDescription
queryNameOrOptionsvalueof string | TypeSpec.Http.QueryOptionsOptional 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", explode: true }) ids: string[]): void;

@route

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

Target

Namespace | Interface | Operation

Parameters

NameTypeDescription
pathvalueof string

Examples

Simple path parameter
@route("/widgets/{id}") op getWidget(@path id: string): Widget;
Reserved characters
@route("/files{+path}") op getFile(@path path: string): bytes;
Query parameter
@route("/files") op list(select?: string, filter?: string): Files[];
@route("/files{?select,filter}") op listFullUriTemplate(select?: string, filter?: string): Files[];

@server

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

Target

Namespace

Parameters

NameTypeDescription
urlvalueof stringServer endpoint
descriptionvalueof stringDescription of the endpoint
parametersRecord<unknown>Optional set of parameters used to interpolate the url.

Examples

@service
@server("https://example.com")
namespace PetStore;
With a description
@service
@server("https://example.com", "Single server endpoint")
namespace PetStore;
Parameterized
@server("https://{region}.foo.com", "Regional endpoint", {
  @doc("Region name")
  region?: string = "westus",
})
Multiple
@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

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

NameTypeDescription
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;