rest

@typespec/rest

TypeSpec REST protocol binding

Install

npm install @typespec/rest

Decorators

TypeSpec.Rest

• @action
• @actionSeparator
• @autoRoute
• @collectionAction
• @copyResourceKeyParameters
• @createsOrReplacesResource
• @createsOrUpdatesResource
• @createsResource
• @deletesResource
• @listsResource
• @parentResource
• @readsResource
• @resource
• @segment
• @segmentOf
• @updatesResource

@action

Specify this operation is an action. (Scoped to a resource item /pets/{petId}/my-action)

@TypeSpec.Rest.action(name?: valueof string)

Target

Operation

Parameters

Name	Type	Description
name	valueof string	Name of the action. If not specified, the name of the operation will be used.

@actionSeparator

Defines the separator string that is inserted before the action name in auto-generated routes for actions.

When applied to a namespace, the separator applies to all action operations in that namespace and its sub-namespaces. When applied to an interface, the separator applies to all action operations in that interface and overrides any namespace-level separator. When applied to an operation, the separator applies only to that operation and overrides any interface or namespace-level separator.

@TypeSpec.Rest.actionSeparator(seperator: valueof "/" | ":" | "/:")

Target

Operation | Interface | Namespace

Parameters

Name	Type	Description
seperator	valueof "/" | ":" | "/:"	Seperator seperating the action segment from the rest of the url

@autoRoute

This interface or operation should resolve its route automatically. To be used with resource types where the route segments area defined on the models.

@TypeSpec.Rest.autoRoute

Target

Interface | Operation

Parameters

None

Examples

@autoRoute
interface Pets {
  get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
}

@collectionAction

Specify this operation is a collection action. (Scopped to a resource, /pets/my-action)

@TypeSpec.Rest.collectionAction(resourceType: Model, name?: valueof string)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource
name	valueof string	Name of the action. If not specified, the name of the operation will be used.

@copyResourceKeyParameters

Copy the resource key parameters on the model

@TypeSpec.Rest.copyResourceKeyParameters(filter?: valueof string)

Target

Model

Parameters

Name	Type	Description
filter	valueof string	Filter to exclude certain properties.

@createsOrReplacesResource

Specify that this is a CreateOrReplace operation for a given resource.

@TypeSpec.Rest.createsOrReplacesResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@createsOrUpdatesResource

Specify that this is a CreatesOrUpdate operation for a given resource.

@TypeSpec.Rest.createsOrUpdatesResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@createsResource

Specify that this is a Create operation for a given resource.

@TypeSpec.Rest.createsResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@deletesResource

Specify that this is a Delete operation for a given resource.

@TypeSpec.Rest.deletesResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@listsResource

Specify that this is a List operation for a given resource.

@TypeSpec.Rest.listsResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@parentResource

Mark model as a child of the given parent resource.

@TypeSpec.Rest.parentResource(parent: Model)

Target

Model

Parameters

Name	Type	Description
parent	Model	Parent model.

@readsResource

Specify that this is a Read operation for a given resource.

@TypeSpec.Rest.readsResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource

@resource

Mark this model as a resource type with a name.

@TypeSpec.Rest.resource(collectionName: valueof string)

Target

Model

Parameters

Name	Type	Description
collectionName	valueof string	type's collection name

@segment

Defines the preceding path segment for a @path parameter in auto-generated routes.

@TypeSpec.Rest.segment(name: valueof string)

Target

Model | ModelProperty | Operation

Parameters

Name	Type	Description
name	valueof string	Segment that will be inserted into the operation route before the path parameter's name field.

Examples

@autoRoute
interface Pets {
  get(@segment("pets") @path id: string): void; //-> route: /pets/{id}
}

@segmentOf

Returns the URL segment of a given model if it has @segment and @key decorator.

@TypeSpec.Rest.segmentOf(type: Model)

Target

Operation

Parameters

Name	Type	Description
type	Model	Target model

@updatesResource

Specify that this is a Update operation for a given resource.

@TypeSpec.Rest.updatesResource(resourceType: Model)

Target

Operation

Parameters

Name	Type	Description
resourceType	Model	Resource marked with @resource