## TypeSpec.Http ### `AcceptedResponse` {#TypeSpec.Http.AcceptedResponse} The request has been accepted for processing, but processing has not yet completed. ```typespec model TypeSpec.Http.AcceptedResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `202` | The status code. | ### `ApiKeyAuth` {#TypeSpec.Http.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.1 X-API-Key: abcdef12345 ``` or as a cookie ``` GET /something HTTP/1.1 Cookie: X-API-KEY=abcdef12345 ``` ```typespec model TypeSpec.Http.ApiKeyAuth ``` #### Template Parameters | Name | Description | | -------- | --------------------------- | | Location | The location of the API key | | Name | The name of the API key | #### Properties | Name | Type | Description | | ---- | ------------------------------- | ----------- | | type | `TypeSpec.Http.AuthType.apiKey` | | | in | `Location` | | | name | `Name` | | ### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow} Authorization Code flow ```typespec model TypeSpec.Http.AuthorizationCodeFlow ``` #### 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` {#TypeSpec.Http.BadRequestResponse} The server could not understand the request due to invalid syntax. ```typespec model TypeSpec.Http.BadRequestResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `400` | The status code. | ### `BasicAuth` {#TypeSpec.Http.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== ``` ```typespec model TypeSpec.Http.BasicAuth ``` #### Properties | Name | Type | Description | | ------ | ----------------------------- | ------------------- | | type | `TypeSpec.Http.AuthType.http` | Http authentication | | scheme | `"Basic"` | basic auth scheme | ### `BearerAuth` {#TypeSpec.Http.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 ``` ```typespec model TypeSpec.Http.BearerAuth ``` #### Properties | Name | Type | Description | | ------ | ----------------------------- | ------------------- | | type | `TypeSpec.Http.AuthType.http` | Http authentication | | scheme | `"Bearer"` | bearer auth scheme | ### `Body` {#TypeSpec.Http.Body} 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. ```typespec model TypeSpec.Http.Body ``` #### Template Parameters | Name | Description | | ---- | ---------------------------------------- | | Type | The type of the model's `body` property. | #### Properties | Name | Type | Description | | ---- | ------ | ----------- | | body | `Type` | | ### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow} Client credentials flow ```typespec model TypeSpec.Http.ClientCredentialsFlow ``` #### 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` {#TypeSpec.Http.ConflictResponse} The request conflicts with the current state of the server. ```typespec model TypeSpec.Http.ConflictResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `409` | The status code. | ### `CookieOptions` {#TypeSpec.Http.CookieOptions} Cookie Options. ```typespec model TypeSpec.Http.CookieOptions ``` #### Properties | Name | Type | Description | | ----- | -------- | ------------------- | | name? | `string` | Name in the cookie. | ### `CreatedResponse` {#TypeSpec.Http.CreatedResponse} The request has succeeded and a new resource has been created as a result. ```typespec model TypeSpec.Http.CreatedResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `201` | The status code. | ### `File` {#TypeSpec.Http.File} 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`: The `Content-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`: The `filename` parameter value of the `Content-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": , "filename": , "contents": } ``` 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: ; 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. ```typespec model TypeSpec.Http.File ``` #### 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 ```tsp // Download a file @get op download(): File; // Upload a file @post op upload(@bodyRoot file: File): void; ``` ```tsp // Upload and download files in a multipart payload op multipartFormDataUpload( @multipartBody fields: { files: HttpPart[]; }, ): void; op multipartFormDataDownload(): { @multipartBody formFields: { files: HttpPart[]; }; }; ``` ```tsp // 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; ``` ```tsp // Declare a custom type of binary file model 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; ``` ````tsp // 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":,"filename":,"contents":}` @get op downloadTextFileJson(): { @header contentType: "application/json", @body file: File<"text/plain", string>, }; // The request body is a JSON object like `{"contentType":,"filename":,"contents":}` @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.

In file bodies, this value comes from the `Content-Type` header of the request or response. In JSON bodies,
this value is serialized as a field in the response.

NOTE: this is not _necessarily_ the same as the `Content-Type` header of the request or response, but
it will be for file bodies. It may be different if the file is serialized as a JSON object. It always refers to the
_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.

In file bodies, this value comes from the `filename` parameter of the `Content-Disposition` header of the response
or multipart payload. In JSON bodies, this value is serialized as a field in the response.

NOTE: By default, `filename` cannot be sent in request payloads and can only be sent in responses and multipart
payloads, as the `Content-Disposition` header is not valid in requests. If you want to send the `filename` in a request,
you must extend the `File` model and override the `filename` property with a different location defined by HTTP metadata
decorators. | | contents | `Contents` | The contents of the file.

In file bodies, this value comes from the body of the request, response, or multipart payload. In JSON bodies,
this value is serialized as a field in the response. | ### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse} Access is forbidden. ```typespec model TypeSpec.Http.ForbiddenResponse ```` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `403` | The status code. | ### `HeaderOptions` {#TypeSpec.Http.HeaderOptions} Header options. ```typespec model TypeSpec.Http.HeaderOptions ``` #### 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](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)

\| 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` {#TypeSpec.Http.HttpPart} ```typespec model TypeSpec.Http.HttpPart ``` #### Template Parameters | Name | Description | | ------- | ----------- | | Type | | | Options | | #### Properties None ### `HttpPartOptions` {#TypeSpec.Http.HttpPartOptions} ```typespec model TypeSpec.Http.HttpPartOptions ``` #### Properties | Name | Type | Description | | ----- | -------- | ------------------------------------------- | | name? | `string` | Name of the part when using the array form. | ### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow} Implicit flow ```typespec model TypeSpec.Http.ImplicitFlow ``` #### 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 | ### `Link` {#TypeSpec.Http.Link} ```typespec model TypeSpec.Http.Link ``` #### Properties | Name | Type | Description | | ----------- | ----------------- | ----------- | | target | `url` | | | rel | `string` | | | attributes? | `Record` | | ### `LocationHeader` {#TypeSpec.Http.LocationHeader} The Location header contains the URL where the status of the long running operation can be checked. ```typespec model TypeSpec.Http.LocationHeader ``` #### Properties | Name | Type | Description | | -------- | -------- | --------------------------------------------------------------------------------------------------- | | location | `string` | The Location header contains the URL where the status of the long running operation can be checked. | ### `MovedResponse` {#TypeSpec.Http.MovedResponse} The URL of the requested resource has been changed permanently. The new URL is given in the response. ```typespec model TypeSpec.Http.MovedResponse ``` #### 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` {#TypeSpec.Http.NoAuth} This authentication option signifies that API is not secured at all. It might be useful when overriding authentication on interface of operation level. ```typespec model TypeSpec.Http.NoAuth ``` #### Properties | Name | Type | Description | | ---- | ------------------------------- | ----------- | | type | `TypeSpec.Http.AuthType.noAuth` | | ### `NoContentResponse` {#TypeSpec.Http.NoContentResponse} There is no content to send for this request, but the headers may be useful. ```typespec model TypeSpec.Http.NoContentResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `204` | The status code. | ### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse} The server cannot find the requested resource. ```typespec model TypeSpec.Http.NotFoundResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `404` | The status code. | ### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse} The client has made a conditional request and the resource has not been modified. ```typespec model TypeSpec.Http.NotModifiedResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `304` | The status code. | ### `OAuth2Auth` {#TypeSpec.Http.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. ```typespec model TypeSpec.Http.OAuth2Auth ``` #### 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 | Name | Type | Description | | ------------- | ------------------------------- | ----------- | | type | `TypeSpec.Http.AuthType.oauth2` | | | flows | `Flows` | | | defaultScopes | `Scopes` | | ### `OkResponse` {#TypeSpec.Http.OkResponse} The request has succeeded. ```typespec model TypeSpec.Http.OkResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `200` | The status code. | ### `OpenIdConnectAuth` {#TypeSpec.Http.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 ```http https://server.com/.well-known/openid-configuration ``` ```typespec model TypeSpec.Http.OpenIdConnectAuth ``` #### Template Parameters | Name | Description | | ---------- | ----------- | | ConnectUrl | | #### 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` {#TypeSpec.Http.PasswordFlow} Resource Owner Password flow ```typespec model TypeSpec.Http.PasswordFlow ``` #### 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` {#TypeSpec.Http.PatchOptions} Options for PATCH operations. ```typespec model TypeSpec.Http.PatchOptions ``` #### Properties | Name | Type | Description | | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- | | implicitOptionality? | `boolean` | If set to `false`, disables the implicit transform that makes the body of a
PATCH operation deeply optional. | ### `PathOptions` {#TypeSpec.Http.PathOptions} ```typespec model TypeSpec.Http.PathOptions ``` #### 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](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | | 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](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3) | ### `PlainData` {#TypeSpec.Http.PlainData} Produces a new model with the same properties as T, but with `@query`, `@header`, `@body`, and `@path` decorators removed from all properties. ```typespec model TypeSpec.Http.PlainData ``` #### Template Parameters | Name | Description | | ---- | -------------------------------------- | | Data | The model to spread as the plain data. | #### Properties None ### `QueryOptions` {#TypeSpec.Http.QueryOptions} Query parameter options. ```typespec model TypeSpec.Http.QueryOptions ``` #### 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](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3)

\| 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` {#TypeSpec.Http.Response} Describes an HTTP response. ```typespec model TypeSpec.Http.Response ``` #### Template Parameters | Name | Description | | ------ | -------------------------------- | | Status | The status code of the response. | #### Properties | Name | Type | Description | | ---------- | -------- | ----------- | | statusCode | `Status` | | ### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse} Access is unauthorized. ```typespec model TypeSpec.Http.UnauthorizedResponse ``` #### Properties | Name | Type | Description | | ---------- | ----- | ---------------- | | statusCode | `401` | The status code. | ### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation} Describes the location of the API key ```typespec 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` {#TypeSpec.Http.AuthType} Authentication type ```typespec enum TypeSpec.Http.AuthType ``` | Name | Value | Description | | ------------- | ----- | -------------- | | http | | HTTP | | apiKey | | API key | | oauth2 | | OAuth2 | | openIdConnect | | OpenID connect | | noAuth | | Empty auth | ### `OAuth2FlowType` {#TypeSpec.Http.OAuth2FlowType} Describes the OAuth2 flow type ```typespec enum TypeSpec.Http.OAuth2FlowType ``` | Name | Value | Description | | ----------------- | ----- | ----------------------- | | authorizationCode | | authorization code flow | | implicit | | implicit flow | | password | | password flow | | clientCredentials | | client credential flow | ### `LinkHeader` {#TypeSpec.Http.LinkHeader} ```typespec scalar TypeSpec.Http.LinkHeader ```