Skip to content

Latest commit

 

History

History
 
 

rest

README.md

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:

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