Skip to content

Latest commit

 

History

History
 
 

rest

Folders and files

NameName
Last commit message
Last commit date

parent directory

..

lib

lib

 
 

src

src

 
 

test

test

 
 

.c8rc.json

.c8rc.json

 
 

.eslintrc.cjs

.eslintrc.cjs

 
 

.mocharc.yaml

.mocharc.yaml

 
 

CHANGELOG.json

CHANGELOG.json

 
 

CHANGELOG.md

CHANGELOG.md

 
 

LICENSE

LICENSE

 
 

README.md

README.md

 
 

mocha.reporter.config.json

mocha.reporter.config.json

 
 

package.json

package.json

 
 

tsconfig.json

tsconfig.json

 
 

README.md

TypeSpec HTTP/Rest Library

This package provides TypeSpec decorators, models, and interfaces to describe HTTP and REST API. With fundamental models and decorators defined in TypeSpec.Http namespace, you will be able describe basic http level operations. TypeSpec.Rest namespace adds additional predefined models and interfaces. 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.Http;
using TypeSpec.Rest;

See Http and rest.

Library Tour

@typespec/rest library defines of the following artifacts:

Models

  • HTTP namespace

    Model Notes
    LocationHeader Location header
    Response<Status> <Status> is numerical status code.
    OkResponse<T> Response<200> with T as the response body model type.
    CreatedResponse Response<201>
    AcceptedResponse Response<202>
    NoContentResponse Response<204>
    MovedResponse Response<301> with LocationHeader for redirected URL
    NotModifiedResponse Response<304>
    UnauthorizedResponse Response<401>
    NotFoundResponse Response<404>
    ConflictResponse Response<409>
    PlainData<T> Produces a new model with the same properties as T, but with @query, @header, @body, and @path decorators removed from all properties.
    BasicAuth Configure basic authentication with @useAuth
    BearerAuth Configure bearer authentication with @useAuth
    ApiKeyAuth<TLocation, TName> Configure apiKey authentication with @useAuth
    OAuth2Auth Configure oauth2 authentication with @useAuth

  • REST namespace

    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

  • HTTP namespace

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

Declarator Scope Usage
@get operations indicating operation uses HTTP GET verb.
@put operations indicating operation uses HTTP PUT verb.
@post operations indicating operation uses HTTP POST verb.
@patch operations indicating operation uses HTTP PATCH verb.
@delete operations indicating operation uses HTTP DEL verb.
@head operations indicating operation uses HTTP HEAD verb.
@header model properties and operation parameters indicating the properties are request or response headers.
@query model properties and operation parameters indicating the properties are in the request query string.
@body model properties and operation parameters indicating the property is in request or response body. Only one allowed per model and operation.
@path model properties and operation parameters indicating the properties are in request path.
@statusCode model properties and operation parameters indicating the property is the return status code. Only one allowed per model.
@server namespace Configure the server url for the service.
@route operations, namespaces, interfaces Syntax:
@route(routeString)

Note:
@route defines the relative route URI for the target operation. The routeString argument should be a URI fragment that may contain one or more path parameter fields. If the namespace or interface that contains the operation is also marked with a @route decorator, it will be used as a prefix to the route URI of the operation.
@useAuth namespace Configure the service authentication.

  • REST namespace

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

  • HTTP namespace

    None

  • REST namespace

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.

How to

Specify content type

To specify the content type you can add a @header contentType: <value> in the operation parameter(For request content type) or return type(For response content type)

Example: return application/png byte body

op getPng(): {
  @header contentType: "application/png";
  @body _: bytes;
};

Example: expect application/png byte body

op getPng(@header contentType: "application/png", @body _: bytes): void;

See also