@typespec/rest

TypeSpec REST Library

This package provides TypeSpec decorators, models, and interfaces to describe APIs using the REST style. These building blocks make defining REST resources and operations based on standard patterns extremely simple.

Install

In your TypeSpec project root

npm install @typespec/rest

Usage

import "@typespec/rest";

using TypeSpec.Rest;

See Http and rest.

Library Tour

@typespec/rest library defines of the following artifacts:

• TypeSpec HTTP/Rest Library
  • Install
  • Usage
  • Library Tour
  • Models
  • Decorators
  • Interfaces
  • See also

Models

Model	Notes
KeysOf<T>	Dynamically gathers keys of the model type T.
Page<T>	A model defines page of T which includes an array of T and optional next link.
ParentKeysOf<T>	Dynamically gathers parent keys of the model type T, which are referenced with @parentResource decorator.
ResourceError	The default error response for resource operations that includes code: int32 and message string.
ResourceParameters<TResource>	Represents operation parameters for resource TResource. Default to KeysOf<T>.
ResourceCollectionParameters<TResource>	Represents collection operation parameters for resource TResource. Default to ParentKeysOf<T>
ResourceCreatedResponse<T>	Resource create operation completed successfully.
ResourceDeletedResponse	Resource deleted successfully.

Decorators

The @typespec/rest library defines the following decorators in TypeSpec.Rest namespace:

Declarator	Scope	Syntax
@discriminator	models	Syntax: @discriminator(kindString) Note: @discriminator allows defining polymorphic models to be used by API as parameters and return types. In many strongly typed languages, they are expressed as inheritance.
@resource	Model	Syntax: @resource(collectionName) Note: This decorator is to used to mark a model as a resource type with a name for the type's collection.
@readsResource	operations	Syntax: @readsResource(modelType) Note: This decorator is to used to signal the operation that is the Read operation for a particular resource.
@createsResource	operations	Syntax: @createsResource(modelType) Note: This decorator is to used to signal the operation that is the Create operation for a particular resource.
@createsOrUpdatesResource	operations	Syntax: @createsOrUpdatesResource(modelType) Note: This decorator is to used to signal the operation that is the CreatesOrUpdate operation for a particular resource.
@updatesResource	operations	Syntax: @updatesResource(modelType) Note: This decorator is to used to signal the operation that is the Update operation for a particular resource.
@deletesResource	operations	Syntax: @deletesResource(modelType) Note: This decorator is to used to signal the operation that is the Delete operation for a particular resource.
@listsResource	operations	Syntax: @listsResource(modelType) Note: This decorator is to used to signal the operation that is the List operation for a particular resource.
@parentResource	models	Syntax: @parentResource(parentModelTypeReference) Note: @parentResource marks a model property with a reference to its parent resource type. The first argument should be a reference to a model type which will be treated as the parent type of the target model type. This will cause the @key properties of all parent types of the target type to show up in operations of the Resource*<T> interfaces defined in this library.
@segment	model properties, operation parameters	Syntax: @segment(segmentString) Note: @segment defines the preceding path segment for a @path parameter in auto-generated routes. The first argument should be a string that will be inserted into the operation route before the path parameter's name field. For example: op getUser(@path @segment("users") userId: string): User will produce the route /users/{userId}.
@segmentOf	models	Syntax: @segment(segmentString) Note: @segmentOf returns the URL segment of a given model if it has @segment and @key decorator.
@segmentSeparator	model properties, operation parameters, or operations	Syntax: @segmentSeparator(separatorString) Note: @segmentSeparator defines the separator string that is inserted between the target's @segment and the preceding route path in auto-generated routes. The first argument should be a string that will be inserted into the operation route before the target's @segment value. Can be a string of any length. Defaults to /.
@actionSeparator	model properties, operation parameters, or operations	Syntax: @actionSeparator(separatorString) Note: @actionSeparator defines the separator string that is inserted before the action name in auto-generated routes for actions.
@autoRoute	operations	Syntax: @autoRoute() Note: @autoRoute enables automatic route generation for an operation, namespace, or interface. When applied to an operation, it automatically generates the operation's route based on path parameter metadata. When applied to a namespace or interface, it causes all operations under that scope to have auto-generated routes.

Interfaces

These standard interfaces defines resource operations in basic building blocks that you can expose on the resources. You can use extends to compose the operations to meet the exact needs of your resource APIs.

For example, for below Widget model

@resource("widgets")
model Widget {
  @key id: string;
  name: string;
}

• Widget resource supports full CRUDL operations.

interface WidgetService extends Resource.ResourceOperations<Widget, Error>;

• Widget resource supports only CRD operations.

interface WidgetService
   extends Resource.ResourceRead<Widget, Error>,
    Resource.ResourceCreate<Widget, Error>,
    Resource.ResourceDelete<Widget, Error> {
}

Interfaces	Notes
ResourceRead<TResource, TError>	Resource GET operation
ResourceCreateOrUpdate<TResource, TError>	Resource PUT operation
ResourceCreate<TResource, TError>	Resource POST operation
ResourceUpdate<TResource, TError>	Resource PATCH operation
ResourceDelete<TResource, TError>	Resource DEL operation
ResourceList<TResource, TError>	Resource LIST operation which is a GET operation from a parent resource.
ResourceInstanceOperations<TResource, TError>	Combines resource GET + PATCH + DEL operations
ResourceCollectionOperations<TResource, TError>	Combines resource POST + LIST operations
ResourceOperations<TResource, TError>	Combines resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST
SingletonResourceRead<TSingleton, TResource, TError>	Singleton resource GET operation.
SingletonResourceUpdate<TSingleton, TResource, TError>	Singleton resource PATCH operation.
SingletonResourceOperations<TSingleton, TResource, TError>	Combines resource GET + PATCH operations
ExtensionResourceRead<TExtension, TResource, TError>	Extension resource GET operation.
ExtensionResourceCreateOrUpdate<TExtension, TResource, TError>	Extension resource PUT operation
ExtensionResourceCreate<TExtension, TResource, TError>	Extension resource POST operation
ExtensionResourceUpdate<TExtension, TResource, TError>	Extension resource PATCH operation
ExtensionResourceDelete<TExtension, TResource, TError>	Extension resource GET operation
ExtensionResourceList<TExtension, TResource, TError>	Extension resource LIST operation which is a GET operation from a parent resource.
ExtensionResourceInstanceOperations<TExtension, TResource, TError>	Combines extension resource GET + PATCH + DEL operations.
ExtensionResourceCollectionOperations<TExtension, TResource, TError>	Combines extension resource POST + LIST operations.
ExtensionResourceOperations<TExtension, TResource, TError>	Combines extension resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST operations.

See also

• REST example:
• TypeSpec Getting Started
• TypeSpec Website