@typespec/http
TypeSpec HTTP protocol binding
Install
npm install @typespec/http copy
Usage
Add the following in tspconfig.yaml:
linter :
extends :
- "@typespec/http/all" copy
RuleSets
Available ruleSets:
Rules
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.
Target
ModelProperty
Parameters
None
Examples
op upload ( @body image : bytes ) : void ;
op download () : {
@body image : bytes ;
}; copy
@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 copy
Target
ModelProperty
Parameters
None
Examples
op upload (
name : string ,
@bodyIgnore headers : {
@header id : string ;
},
) : void ; copy
@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 copy
Target
ModelProperty
Parameters
None
Examples
op upload (
@bodyRoot user : {
name : string ;
@header id : string ;
},
) : void ;
op download () : {
@bodyRoot user : {
name : string ;
@header id : string ;
};
}; copy
@cookie
Specify this property is to be sent or received in the cookie.
@TypeSpec.Http.cookie ( cookieNameOrOptions ?: valueof string | TypeSpec . Http . CookieOptions ) copy
Target
ModelProperty
Parameters
Name Type Description cookieNameOrOptions valueof 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 ; copy
op read () : {
@cookie authToken : string ;
}; // headerName: auth_token
op update ( @cookie AuthToken : string ) : void ; // headerName: auth_token copy
@delete
Specify the HTTP verb for the target operation to be DELETE.
@TypeSpec.Http.delete copy
Target
Operation
Parameters
None
Examples
@delete op set (petId : string ) : void ; copy
@get
Specify the HTTP verb for the target operation to be GET.
Target
Operation
Parameters
None
Examples
@get op read () : string ; copy
@head
Specify the HTTP verb for the target operation to be HEAD.
Target
Operation
Parameters
None
Examples
@head op ping (petId : string ) : void ; copy
Specify this property is to be sent or received as an HTTP header.
@TypeSpec.Http.header ( headerNameOrOptions ?: valueof string | TypeSpec . Http . HeaderOptions ) copy
Target
ModelProperty
Parameters
Name Type Description headerNameOrOptions valueof 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 ; copy
op read () : {
@header contentType : string ;
}; // headerName: content-type
op update ( @header ifMatch : string ) : void ; // headerName: if-match copy
@multipartBody
Specify that the target property is the body of a multipart request or response.
The property type must be a model or tuple whose members are all HttpPart, each describing one
part of the payload.
@TypeSpec.Http.multipartBody copy
Target
ModelProperty
Parameters
None
Examples
op upload (
@header `content-type` : "multipart/form-data" ,
@multipartBody body : {
fullName : HttpPart < string >;
headShots : HttpPart < Image >[];
},
) : void ; copy
@patch
Specify the HTTP verb for the target operation to be PATCH.
@TypeSpec.Http.patch ( options ?: valueof TypeSpec . Http . PatchOptions ) copy
Target
Operation
Parameters
Examples
@patch op update (pet : Pet ) : void ; copy
Using MergePatch template for proper merge-patch semantics
@patch op update ( @body pet : MergePatchUpdate < Pet >) : void ; copy
@path
Explicitly specify that this property is to be interpolated as a path parameter.
@TypeSpec.Http.path ( paramNameOrOptions ?: valueof string | TypeSpec . Http . PathOptions ) copy
Target
ModelProperty
Parameters
Name Type Description paramNameOrOptions valueof 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 ; copy
@post
Specify the HTTP verb for the target operation to be POST.
Target
Operation
Parameters
None
Examples
@post op create (pet : Pet ) : void ; copy
@put
Specify the HTTP verb for the target operation to be PUT.
Target
Operation
Parameters
None
Examples
@put op set (pet : Pet ) : void ; copy
@query
Specify this property is to be sent as a query parameter.
@TypeSpec.Http.query ( queryNameOrOptions ?: valueof string | TypeSpec . Http . QueryOptions ) copy
Target
ModelProperty
Parameters
Name Type Description queryNameOrOptions valueof 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 ; copy
@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 ) copy
Target
Namespace | Interface | Operation
Parameters
Name Type Description path valueof stringURI template for this operation.
Examples
Simple path parameter
@route ( "/widgets/{id}" ) op getWidget ( @path id : string ) : Widget ; copy
Reserved characters
@route ( "/files{+path}" ) op getFile ( @path path : string ) : bytes ; copy
Query parameter
@route ( "/files" ) op list (select ?: string , filter ?: string ) : Files [];
@route ( "/files{?select,filter}" ) op listFullUriTemplate (select ?: string , filter ?: string ) : Files []; copy
@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 >) copy
Target
Namespace
Parameters
Name Type Description url valueof stringServer endpoint description valueof stringDescription of the endpoint parameters Record<unknown>Optional set of parameters used to interpolate the url.
Examples
@service
@server ( "https://example.com" )
namespace PetStore ; copy
With a description
@service
@server ( "https://example.com" , "Single server endpoint" )
namespace PetStore ; copy
Parameterized
@server ( "https://{region}.foo.com" , "Regional endpoint" , {
@doc ( "Region name" )
region ?: string = "westus" ,
}) copy
Multiple
@service
@server ( "https://example.com" , "Standard endpoint" )
@server (
"https://{project}.private.example.com" ,
"Private project endpoint" ,
{
project : string ,
}
)
namespace PetStore ; copy
@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 ; copy
@TypeSpec.Http.sharedRoute copy
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 copy
Target
ModelProperty
Parameters
None
Examples
op read () : {
@statusCode _ : 200 ;
@body pet : Pet ;
};
op create () : {
@statusCode _ : 201 | 202 ;
}; copy
@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 | {}[]) copy
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 ; copy