Skip to content

Latest commit

 

History

History
572 lines (381 loc) · 12.2 KB

README.md

File metadata and controls

572 lines (381 loc) · 12.2 KB

@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

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

@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.

@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
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?: { shared: boolean })
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;