Data types
TypeSpec.Http
Section titled “TypeSpec.Http”AcceptedResponse
Section titled “AcceptedResponse”The request has been accepted for processing, but processing has not yet completed.
model TypeSpec.Http.AcceptedResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 202 | The status code. |
ApiKeyAuth
Section titled “ApiKeyAuth”An API key is a token that a client provides when making API calls. The key can be sent in the query string:
GET /something?api_key=abcdef12345
or as a request header
GET /something HTTP/1.1X-API-Key: abcdef12345
or as a cookie
GET /something HTTP/1.1Cookie: X-API-KEY=abcdef12345
model TypeSpec.Http.ApiKeyAuth<Location, Name>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Location | The location of the API key |
Name | The name of the API key |
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.apiKey | |
in | Location | |
name | Name |
AuthorizationCodeFlow
Section titled “AuthorizationCodeFlow”Authorization Code flow
model TypeSpec.Http.AuthorizationCodeFlow
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.OAuth2FlowType.authorizationCode | authorization code flow |
authorizationUrl | string | the authorization URL |
tokenUrl | string | the token URL |
refreshUrl? | string | the refresh URL |
scopes? | string[] | list of scopes for the credential |
BadRequestResponse
Section titled “BadRequestResponse”The server could not understand the request due to invalid syntax.
model TypeSpec.Http.BadRequestResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 400 | The status code. |
BasicAuth
Section titled “BasicAuth”Basic authentication is a simple authentication scheme built into the HTTP protocol.
The client sends HTTP requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.
For example, to authorize as demo / p@55w0rd
the client would send
Authorization: Basic ZGVtbzpwQDU1dzByZA==
model TypeSpec.Http.BasicAuth
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.http | Http authentication |
scheme | "Basic" | basic auth scheme |
BearerAuth
Section titled “BearerAuth”Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>
model TypeSpec.Http.BearerAuth
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.http | Http authentication |
scheme | "Bearer" | bearer auth scheme |
Defines a model with a single property of the given type, marked with @body
.
This can be useful in situations where you cannot use a bare type as the body and it is awkward to add a property.
model TypeSpec.Http.Body<Type>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Type | The type of the model’s body property. |
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
body | Type |
ClientCredentialsFlow
Section titled “ClientCredentialsFlow”Client credentials flow
model TypeSpec.Http.ClientCredentialsFlow
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.OAuth2FlowType.clientCredentials | client credential flow |
tokenUrl | string | the token URL |
refreshUrl? | string | the refresh URL |
scopes? | string[] | list of scopes for the credential |
ConflictResponse
Section titled “ConflictResponse”The request conflicts with the current state of the server.
model TypeSpec.Http.ConflictResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 409 | The status code. |
CookieOptions
Section titled “CookieOptions”Cookie Options.
model TypeSpec.Http.CookieOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
name? | string | Name in the cookie. |
CreatedResponse
Section titled “CreatedResponse”The request has succeeded and a new resource has been created as a result.
model TypeSpec.Http.CreatedResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 201 | The status code. |
A file in an HTTP request, response, or multipart payload.
Files have a special meaning that the HTTP library understands. When the body of an HTTP request, response,
or multipart payload is effectively an instance of TypeSpec.Http.File
or any type that extends it, the
operation is treated as a file upload or download.
When using file bodies, the fields of the file model are defined to come from particular locations by default:
contentType
: TheContent-Type
header of the request, response, or multipart payload (CANNOT be overridden or changed).contents
: The body of the request, response, or multipart payload (CANNOT be overridden or changed).filename
: Thefilename
parameter value of theContent-Disposition
header of the response or multipart payload (MAY be overridden or changed).
A File may be used as a normal structured JSON object in a request or response, if the request specifies an explicit
Content-Type
header. In this case, the entire File model is serialized as if it were any other model. In a JSON payload,
it will have a structure like:
{ "contentType": <string?>, "filename": <string?>, "contents": <string, base64>}
The contentType
within the file defines what media types the data inside the file can be, but if the specification
defines a Content-Type
for the payload as HTTP metadata, that Content-Type
metadata defines how the file is
serialized. See the examples below for more information.
NOTE: The filename
and contentType
fields are optional. Furthermore, the default location of filename
(Content-Disposition: <disposition>; filename=<filename>
) is only valid in HTTP responses and multipart payloads. If
you wish to send the filename
in a request, you must use HTTP metadata decorators to describe the location of the
filename
field. You can combine the metadata decorators with @visibility
to control when the filename
location
is overridden, as shown in the examples below.
model TypeSpec.Http.File<ContentType, Contents>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
ContentType | The allowed media (MIME) types of the file contents. |
Contents | The type of the file contents. This can be string , bytes , or any scalar that extends them. |
Examples
Section titled “Examples”// Download a file@get op download(): File;
// Upload a file@post op upload(@bodyRoot file: File): void;
// Upload and download files in a multipart payloadop multipartFormDataUpload( @multipartBody fields: { files: HttpPart<File>[]; },): void;
op multipartFormDataDownload(): { @multipartBody formFields: { files: HttpPart<File>[]; };};
// Declare a custom type of text file, where the filename goes in the path// in requests.model SpecFile extends File<"application/json" | "application/yaml", string> { // Provide a header that contains the name of the file when created or updated @header("x-filename") @path filename: string;}
@get op downloadSpec(@path name: string): SpecFile;
@post op uploadSpec(@bodyRoot spec: SpecFile): void;
// Declare a custom type of binary filemodel ImageFile extends File { contentType: "image/png" | "image/jpeg"; @path filename: string;}
@get op downloadImage(@path name: string): ImageFile;
@post op uploadImage(@bodyRoot image: ImageFile): void;
// Use a File as a structured JSON object. The HTTP library will warn you that the File will be serialized as JSON,// so you should suppress the warning if it's really what you want instead of a binary file upload/download.
// The response body is a JSON object like `{"contentType":<string?>,"filename":<string?>,"contents":<string>}`@get op downloadTextFileJson(): { @header contentType: "application/json", @body file: File<"text/plain", string>,};
// The request body is a JSON object like `{"contentType":<string?>,"filename":<string?>,"contents":<base64>}`@post op uploadBinaryFileJson( @header contentType: "application/json", @body file: File<"image/png", bytes>,): void;
#### Properties| Name | Type | Description ||------|------|-------------|| contentType? | `ContentType` | The allowed media (MIME) types of the file contents.<br /><br />In file bodies, this value comes from the `Content-Type` header of the request or response. In JSON bodies,<br />this value is serialized as a field in the response.<br /><br />NOTE: this is not _necessarily_ the same as the `Content-Type` header of the request or response, but<br />it will be for file bodies. It may be different if the file is serialized as a JSON object. It always refers to the<br />_contents_ of the file, and not necessarily the way the file itself is transmitted or serialized. || filename? | `string` | The name of the file, if any.<br /><br />In file bodies, this value comes from the `filename` parameter of the `Content-Disposition` header of the response<br />or multipart payload. In JSON bodies, this value is serialized as a field in the response.<br /><br />NOTE: By default, `filename` cannot be sent in request payloads and can only be sent in responses and multipart<br />payloads, as the `Content-Disposition` header is not valid in requests. If you want to send the `filename` in a request,<br />you must extend the `File` model and override the `filename` property with a different location defined by HTTP metadata<br />decorators. || contents | `Contents` | The contents of the file.<br /><br />In file bodies, this value comes from the body of the request, response, or multipart payload. In JSON bodies,<br />this value is serialized as a field in the response. |
### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}
Access is forbidden.```typespecmodel TypeSpec.Http.ForbiddenResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 403 | The status code. |
HeaderOptions
Section titled “HeaderOptions”Header options.
model TypeSpec.Http.HeaderOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
name? | string | Name of the header when sent over HTTP. |
explode? | boolean | Equivalent of adding * in the path parameter as per RFC-6570| Style | Explode | Primitive value = 5 | Array = [3, 4, 5] | Object = {“role”: “admin”, “firstName”: “Alex”} | | ------ | ------- | ------------------- | ----------------- | ----------------------------------------------- | | simple | false | 5 | 3,4,5 | role,admin,firstName,Alex || simple | true | 5 | 3,4,5 | role=admin,firstName=Alex | |
HttpPart
Section titled “HttpPart”model TypeSpec.Http.HttpPart<Type, Options>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Type | |
Options |
Properties
Section titled “Properties”None
HttpPartOptions
Section titled “HttpPartOptions”model TypeSpec.Http.HttpPartOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
name? | string | Name of the part when using the array form. |
ImplicitFlow
Section titled “ImplicitFlow”Implicit flow
model TypeSpec.Http.ImplicitFlow
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.OAuth2FlowType.implicit | implicit flow |
authorizationUrl | string | the authorization URL |
refreshUrl? | string | the refresh URL |
scopes? | string[] | list of scopes for the credential |
model TypeSpec.Http.Link
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
target | url | |
rel | string | |
attributes? | Record<unknown> |
LocationHeader
Section titled “LocationHeader”The Location header contains the URL where the status of the long running operation can be checked.
model TypeSpec.Http.LocationHeader
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
location | string | The Location header contains the URL where the status of the long running operation can be checked. |
MergePatchCreateOrUpdate
Section titled “MergePatchCreateOrUpdate”Create a MergePatch Request body for creating or updating the given resource Model. The MergePatch request created by this template provides a TypeSpec description of a JSON MergePatch request that can successfully create or update the given resource. The transformation follows the definition of JSON MergePatch requests in rfc 7396: https://www.rfc-editor.org/rfc/rfc7396, applying the merge-patch transform recursively to keyed types in the resource Model.
Using this template in a PATCH request body overrides the implicitOptionality
setting for PATCH operations and sets application/merge-patch+json
as the request
content-type.
model TypeSpec.Http.MergePatchCreateOrUpdate<T, NameTemplate>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
T | The type of the resource to create a MergePatch update request body for. |
NameTemplate | A StringTemplate used to name any models created by applying the merge-patch transform to the resource. The default name template is {name}MergePatchCreateOrUpdate ,for example, the merge patch transform of model Widget is named WidgetMergePatchCreateOrUpdate . |
Examples
Section titled “Examples”// An operation updating a 'Widget' using merge-patch@patch op update(@body request: MergePatchCreateOrUpdate<Widget>): Widget;
// An operation updating a 'Widget' using merge-patch@patch op update(@bodyRoot request: MergePatchCreateOrUpdate<Widget>): Widget;
// An operation updating a 'Widget' using merge-patch@patch op update(...MergePatchCreateOrUpdate<Widget>): Widget;
Properties
Section titled “Properties”None
MergePatchUpdate
Section titled “MergePatchUpdate”Create a MergePatch Request body for updating the given resource Model. The MergePatch request created by this template provides a TypeSpec description of a JSON MergePatch request that can successfully update the given resource. The transformation follows the definition of JSON MergePatch requests in rfc 7396: https://www.rfc-editor.org/rfc/rfc7396, applying the merge-patch transform recursively to keyed types in the resource Model.
Using this template in a PATCH request body overrides the implicitOptionality
setting for PATCH operations and sets application/merge-patch+json
as the request
content-type.
model TypeSpec.Http.MergePatchUpdate<T, NameTemplate>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
T | The type of the resource to create a MergePatch update request body for. |
NameTemplate | A StringTemplate used to name any models created by applying the merge-patch transform to the resource. The default name template is {name}MergePatchUpdate ,for example, the merge patch transform of model Widget is named WidgetMergePatchUpdate . |
Examples
Section titled “Examples”// An operation updating a 'Widget' using merge-patch@patch op update(@body request: MergePatchUpdate<Widget>): Widget;
// An operation updating a 'Widget' using merge-patch@patch op update(@bodyRoot request: MergePatchUpdate<Widget>): Widget;
// An operation updating a 'Widget' using merge-patch@patch op update(...MergePatchUpdate<Widget>): Widget;
Properties
Section titled “Properties”None
MovedResponse
Section titled “MovedResponse”The URL of the requested resource has been changed permanently. The new URL is given in the response.
model TypeSpec.Http.MovedResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 301 | The status code. |
location | string | The Location header contains the URL where the status of the long running operation can be checked. |
NoAuth
Section titled “NoAuth”This authentication option signifies that API is not secured at all. It might be useful when overriding authentication on interface of operation level.
model TypeSpec.Http.NoAuth
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.noAuth |
NoContentResponse
Section titled “NoContentResponse”There is no content to send for this request, but the headers may be useful.
model TypeSpec.Http.NoContentResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 204 | The status code. |
NotFoundResponse
Section titled “NotFoundResponse”The server cannot find the requested resource.
model TypeSpec.Http.NotFoundResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 404 | The status code. |
NotModifiedResponse
Section titled “NotModifiedResponse”The client has made a conditional request and the resource has not been modified.
model TypeSpec.Http.NotModifiedResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 304 | The status code. |
OAuth2Auth
Section titled “OAuth2Auth”OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
OAuth relies on authentication scenarios called flows, which allow the resource owner (user) to share the protected content from the resource server without sharing their credentials. For that purpose, an OAuth 2.0 server issues access tokens that the client applications can use to access protected resources on behalf of the resource owner. For more information about OAuth 2.0, see oauth.net and RFC 6749.
model TypeSpec.Http.OAuth2Auth<Flows, Scopes>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Flows | The list of supported OAuth2 flows |
Scopes | The list of OAuth2 scopes, which are common for every flow from Flows . This list is combined with the scopes defined in specific OAuth2 flows. |
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.oauth2 | |
flows | Flows | |
defaultScopes | Scopes |
OkResponse
Section titled “OkResponse”The request has succeeded.
model TypeSpec.Http.OkResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 200 | The status code. |
OpenIdConnectAuth
Section titled “OpenIdConnectAuth”OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. It defines a sign-in flow that enables a client application to authenticate a user, and to obtain information (or “claims”) about that user, such as the user name, email, and so on. User identity information is encoded in a secure JSON Web Token (JWT), called ID token. OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically
https://server.com/.well-known/openid-configuration
model TypeSpec.Http.OpenIdConnectAuth<ConnectUrl>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
ConnectUrl |
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.AuthType.openIdConnect | Auth type |
openIdConnectUrl | ConnectUrl | Connect url. It can be specified relative to the server URL |
PasswordFlow
Section titled “PasswordFlow”Resource Owner Password flow
model TypeSpec.Http.PasswordFlow
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
type | TypeSpec.Http.OAuth2FlowType.password | password flow |
tokenUrl | string | the token URL |
refreshUrl? | string | the refresh URL |
scopes? | string[] | list of scopes for the credential |
PatchOptions
Section titled “PatchOptions”Options for PATCH operations.
model TypeSpec.Http.PatchOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
implicitOptionality? | boolean | If set to false , disables the implicit transform that makes the body of aPATCH operation deeply optional. |
PathOptions
Section titled “PathOptions”model TypeSpec.Http.PathOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
name? | string | Name of the parameter in the uri template. |
explode? | boolean | When interpolating this parameter in the case of array or object expand each value using the given style. Equivalent of adding * in the path parameter as per RFC-6570 |
style? | "simple" | "label" | "matrix" | "fragment" | "path" | Different interpolating styles for the path parameter. - simple : No special encoding.- label : Using . separator.- matrix : ; as separator.- fragment : # as separator.- path : / as separator. |
allowReserved? | boolean | When interpolating this parameter do not encode reserved characters. Equivalent of adding + in the path parameter as per RFC-6570 |
PlainData
Section titled “PlainData”Produces a new model with the same properties as T, but with @query
,
@header
, @body
, and @path
decorators removed from all properties.
model TypeSpec.Http.PlainData<Data>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Data | The model to spread as the plain data. |
Properties
Section titled “Properties”None
QueryOptions
Section titled “QueryOptions”Query parameter options.
model TypeSpec.Http.QueryOptions
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
name? | string | Name of the query when included in the url. |
explode? | boolean | If true send each value in the array/object as a separate query parameter. Equivalent of adding * in the path parameter as per RFC-6570| Style | Explode | Uri Template | Primitive value id = 5 | Array id = [3, 4, 5] | Object id = {“role”: “admin”, “firstName”: “Alex”} | | ------ | ------- | -------------- | ---------------------- | ----------------------- | -------------------------------------------------- | | simple | false | /users{?id} | /users?id=5 | /users?id=3,4,5 | /users?id=role,admin,firstName,Alex || simple | true | /users{?id*} | /users?id=5 | /users?id=3&id=4&id=5 | /users?role=admin&firstName=Alex | |
Response
Section titled “Response”Describes an HTTP response.
model TypeSpec.Http.Response<Status>
Template Parameters
Section titled “Template Parameters”Name | Description |
---|---|
Status | The status code of the response. |
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | Status |
UnauthorizedResponse
Section titled “UnauthorizedResponse”Access is unauthorized.
model TypeSpec.Http.UnauthorizedResponse
Properties
Section titled “Properties”Name | Type | Description |
---|---|---|
statusCode | 401 | The status code. |
ApiKeyLocation
Section titled “ApiKeyLocation”Describes the location of the API key
enum TypeSpec.Http.ApiKeyLocation
Name | Value | Description |
---|---|---|
header | API key is a header value | |
query | API key is a query parameter | |
cookie | API key is found in a cookie |
AuthType
Section titled “AuthType”Authentication type
enum TypeSpec.Http.AuthType
Name | Value | Description |
---|---|---|
http | HTTP | |
apiKey | API key | |
oauth2 | OAuth2 | |
openIdConnect | OpenID connect | |
noAuth | Empty auth |
OAuth2FlowType
Section titled “OAuth2FlowType”Describes the OAuth2 flow type
enum TypeSpec.Http.OAuth2FlowType
Name | Value | Description |
---|---|---|
authorizationCode | authorization code flow | |
implicit | implicit flow | |
password | password flow | |
clientCredentials | client credential flow |
LinkHeader
Section titled “LinkHeader”scalar TypeSpec.Http.LinkHeader