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.
In your typespec project root
npm install @typespec/httpimport "@typespec/http";
using TypeSpec.Http;For more information, consult the HTTP section of the TypeSpec guide.
@typespec/http library defines of the following artifacts:
| 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 |
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. |
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;