@typespec/http

TypeSpec HTTP Library

This package provides TypeSpec decorators, models, and interfaces to describe HTTP APIs. With fundamental models and decorators defined in TypeSpec.Http namespace, you will be able describe basic http level operations.

Install

In your typespec project root

npm install @typespec/http

Usage

import "@typespec/http";

using TypeSpec.Http;

For more information, consult the HTTP and REST section of the TypeSpec guide.

Library Tour

@typespec/http library defines of the following artifacts:

• TypeSpec HTTP Library
  • Install
  • Usage
  • Library Tour
  • Models
  • Decorators
  • See also

Models

Model	Notes
LocationHeader	Location header
Response<Status>	<Status> is numerical status code.
OkResponse<T>	Response<200> with T as the response body model type.
CreatedResponse	Response<201>
AcceptedResponse	Response<202>
NoContentResponse	Response<204>
MovedResponse	Response<301> with LocationHeader for redirected URL
NotModifiedResponse	Response<304>
UnauthorizedResponse	Response<401>
NotFoundResponse	Response<404>
ConflictResponse	Response<409>
PlainData<T>	Produces a new model with the same properties as T, but with @query, @header, @body, and @path decorators removed from all properties.
BasicAuth	Configure basic authentication with @useAuth
BearerAuth	Configure bearer authentication with @useAuth
ApiKeyAuth<TLocation, TName>	Configure apiKey authentication with @useAuth
OAuth2Auth	Configure oauth2 authentication with @useAuth

Decorators

The @typespec/http library defines the following decorators in TypeSpec.Http namespace:

Declarator	Scope	Usage
@get	operations	indicating operation uses HTTP GET verb.
@put	operations	indicating operation uses HTTP PUT verb.
@post	operations	indicating operation uses HTTP POST verb.
@patch	operations	indicating operation uses HTTP PATCH verb.
@delete	operations	indicating operation uses HTTP DEL verb.
@head	operations	indicating operation uses HTTP HEAD verb.
@header	model properties and operation parameters	indicating the properties are request or response headers.
@query	model properties and operation parameters	indicating the properties are in the request query string.
@body	model properties and operation parameters	indicating the property is in request or response body. Only one allowed per model and operation.
@path	model properties and operation parameters	indicating the properties are in request path.
@statusCode	model properties and operation parameters	indicating the property is the return status code. Only one allowed per model.
@server	namespace	Configure the server url for the service.
@route	operations, namespaces, interfaces	Syntax: @route(routeString) Note: @route defines the relative route URI for the target operation. The routeString 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.
@useAuth	namespace	Configure the service authentication.

How to

Specify content type

To specify the content type you can add a @header contentType: <value> in the operation parameter(For request content type) or return type(For response content type)

Example: return application/png byte body

op getPng(): {
  @header contentType: "application/png";
  @body _: bytes;
};

Example: expect application/png byte body

op getPng(@header contentType: "application/png", @body _: bytes): void;

See also

• HTTP example:
• TypeSpec Getting Started
• TypeSpec Website