| Code |
Example Payload |
|
```typespec
op case1(
@header foo: string, //
name: string,
age: int32,
): void;
```
|
```http
POST /
Foo: bar
{
"name": "Rex",
"age": 3
}
```
|
```
|
```typespec
op case2(
body: {
@header foo: string;
name: string;
age: int32;
},
): void;
```
|
```http
POST /
Foo: bar
{
"body": {
"name": "Rex",
"age": 3
}
}
```
|
|
```typespec
op case3(
@body body: {
@header foo: string; // warning: `@header` is ignored
name: string;
age: int32;
},
): void;
```
|
```http
POST /
{
"name": "Rex",
"age": 3
}
```
|
|
```typespec
op case4(
@bodyRoot body: {
@header foo: string;
name: string;
age: int32;
},
): void;
```
|
```http
POST /
Foo: bar
{
"name": "Rex",
"age": 3
}
```
|
|
```typespec
op case5(
// This bodyRoot is a noop and will log a warning
@bodyRoot body: {
@bodyRoot reallyBody: {
@header foo: string;
name: string;
age: int32;
};
},
): void;
```
|
```http
POST /
Foo: bar
{
"name": "Rex",
"age": 3
}
```
|
## Headers
Model properties and parameters that should be passed in a header use the `@header` decorator. The decorator takes the header name as a parameter. If a header name is not provided, it is inferred from the property or parameter name. Let's add `etag` support to our pet store's read operation.
```typespec
@route("/pets")
namespace Pets {
op list(@query skip: int32, @query top: int32): {
@body pets: Pet[];
};
op read(@path petId: int32, @header ifMatch?: string): {
@header eTag: string;
@body pet: Pet;
};
@post
op create(@body pet: Pet): {};
}
```
## Status codes
**Default behavior:**
- `4xx,5xx` if response is marked with `@error`
- `200` otherwise
**Configure:**
Use the `@statusCode` decorator on a property to declare a status code for a response. Generally, setting this to just `int32` isn't particularly useful. Instead, use number literal types to create a discriminated union of response types. Let's add status codes to our responses, and add a 404 response to our read endpoint.
```typespec
@route("/pets")
namespace Pets {
@error
model Error {
code: string;
}
op list(@query skip: int32, @query top: int32): {
@body pets: Pet[]; // statusCode: 200 Implicit
};
op read(@path petId: int32, @header ifMatch?: string):
| {
@statusCode statusCode: 200;
@header eTag: string;
@body pet: Pet;
}
| {
@statusCode statusCode: 404;
};
op create(@body pet: Pet):
| {
@statusCode statusCode: 204;
}
| Error; //statusCode: 4xx,5xx as Error use `@error` decorator
}
```
## Content type
[See the documentation of Content-Types](./content-types.md).
## Built-in response shapes
Since status codes are so common for REST APIs, TypeSpec comes with some built-in types for common status codes so you don't need to declare status codes so frequently.
There is also a `Body