typescript-rest

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>Typescript-rest</title> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> <script src="assets/js/modernizr.js"></script> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">Typescript-rest</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> <input type="checkbox" id="tsd-filter-only-exported" /> <label class="tsd-widget" for="tsd-filter-only-exported">Only exported</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <ul class="tsd-breadcrumb"> <li> <a href="globals.html">Globals</a> </li> </ul> <h1> Typescript-rest</h1> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <h1 id="rest-services-for-typescript">REST Services for Typescript</h1> This is a lightweight annotation-based <a href="http://expressjs.com/">expressjs</a> extension for typescript. It can be used to define your APIs using ES7 decorators. Table of Contents <ul> <li><a href="#">REST Services for Typescript</a><ul> <li><a href="#installation">Installation</a></li> <li><a href="#configuration">Configuration</a></li> <li><a href="#basic-usage">Basic Usage</a></li> <li><a href="#complete-guide">Complete Guide</a><ul> <li><a href="#server">Server</a></li> <li><a href="#path-decorator">@Path Decorator</a><ul> <li><a href="#path-parameters">Path Parameters</a></li> </ul> </li> <li><a href="#http-methods">Http Methods</a></li> <li><a href="#parameters">Parameters</a></li> <li><a href="#service-context">Service Context</a></li> <li><a href="#service-return">Service Return</a><ul> <li><a href="#asynchronous-services">Asynchronous services</a></li> </ul> </li> <li><a href="#errors">Errors</a></li> <li><a href="#types-and-languages">Types and languages</a></li> </ul> </li> </ul> </li> </ul> <h2 id="installation">Installation</h2> This library only works with typescript. Ensure it is installed: <pre><code class="lang-bash">npm install typescript -g </code></pre> To install typescript-rest: <pre><code class="lang-bash">npm install typescript-rest --save </code></pre> <h2 id="configuration">Configuration</h2> Typescript-rest requires the following TypeScript compilation options in your tsconfig.json file: <pre><code class="lang-typescript">{ "compilerOptions": { "experimentalDecorators": true, "emitDecoratorMetadata": true } } </code></pre> <h2 id="basic-usage">Basic Usage</h2> <pre><code class="lang-typescript">import * as express from "express"; import {Server, Path, GET, PathParam} from "typescript-rest"; @Path("/hello") class HelloService { @Path(":name") @GET sayHello( @PathParam('name') name: string): string { return "Hello " + name; } } let app: express.Application = express(); Server.buildServices(app); app.listen(3000, function() { console.log('Rest Server listening on port 3000!'); }); </code></pre> That's it. You can just call now: <pre><code>GET http://localhost:3000/hello/joe </code></pre><h2 id="complete-guide">Complete Guide</h2> This library allows you to use ES7 decorators to configure your services using expressjs. <h3 id="server">Server</h3> The Server class is used to configure the server, like: <pre><code class="lang-typescript">let app: express.Application = express(); Server.setFileDest('/uploads'); Server.buildServices(app); app.listen(3000, function() { console.log('Rest Server listening on port 3000!'); }); </code></pre> Note that Server receives an <code>express.Router</code> instance. Then it configures all the routes based on the decorators used on your classes. So, you can use also any other expressjs feature, like error handlers, middlewares etc without any restriction. <h3 id="-path-decorator">@Path Decorator</h3> The @Path decorator allow us to define a router path for a given endpoint. Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. The characters ?, +, *, and () are subsets of their regular expression counterparts. The hyphen (-) and the dot (.) are interpreted literally by string-based paths. We use <a href="https://www.npmjs.com/package/path-to-regexp">path-to-regexp</a> for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths. Some examples: <pre><code class="lang-typescript">@Path("/hello") class HelloService { } </code></pre> <pre><code class="lang-typescript">@Path("/test/hello") class TestService { } </code></pre> This route path will match acd and abcd: <pre><code class="lang-typescript">@Path("ab?cd") class TestService { } </code></pre> This route path will match abcd, abbcd, abbbcd, and so on: <pre><code class="lang-typescript">@Path("ab+cd") class TestService { } </code></pre> This route path will match abcd, abxcd, abRANDOMcd, ab123cd, and so on: <pre><code class="lang-typescript">@Path("ab*cd") class TestService { } </code></pre> This route path will match /abe and /abcde: <pre><code class="lang-typescript">@Path("/ab(cd)?e") class TestService { } </code></pre> This route path will match butterfly and dragonfly, but not butterflyman, dragonfly man, and so on: <pre><code class="lang-typescript">@Path("/.*fly$/") class TestService { } </code></pre> <h4 id="path-parameters">Path Parameters</h4> Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the req.params object, with the name of the route parameter specified in the path as their respective keys. They can be refered through @PathParam decorator on a service method argument. Some examples: <pre><code class="lang-typescript">@Path("/users") class UserService { @Path("/:userId/books/:bookId") @GET getUserBook(@PathParam("userId") userId: number, @PathParam("bookId") bookId: number): Promise<Book> { //... } } </code></pre> The requested URL <a href="http://localhost:3000/users/34/books/8989">http://localhost:3000/users/34/books/8989</a> would map the parameters as: <pre><code> userId: "34" bookId: "8989" </code></pre>Since the hyphen (-) and the dot (.) are interpreted literally, they can be used along with route parameters for useful purposes. <pre><code>Route path: /flights/:from-:to Request URL: http://localhost:3000/flights/LAX-SFO req.params: { "from": "LAX", "to": "SFO" } </code></pre><pre><code>Route path: /plantae/:genus.:species Request URL: http://localhost:3000/plantae/Prunus.persica req.params: { "genus": "Prunus", "species": "persica" } </code></pre><h3 id="http-methods">Http Methods</h3> We have decorators for each HTTP method. Theses decorators are used on service methods already bound to a Path route to specify the endpoint at which requests can be made. The following decorators can be used: <ul> <li>@GET </li> <li>@POST</li> <li>@PUT</li> <li>@PATCH</li> <li>@DELETE</li> <li>@OPTIONS</li> <li>@HEAD</li> </ul> Some examples: <pre><code class="lang-typescript">@Path("/users") class UserService { @GET getUsers(): Promise<Array<User>> { //... } @GET @Path(":userId") getUser(@PathParam("userId")): Promise<User> { //... } @PUT @Path(":userId") saveUser(@PathParam("userId"), user: User): void { //... } } </code></pre> Only methods decorated with one of this HTTP method decorators are exposed as handlers for requests on the server. A single method can only be decorated with one of those decorators at a time. <h3 id="parameters">Parameters</h3> There are decorators to map parameters to arguments on service methods. Each decorator can map a differente kind of parameter on request. The following decorators are available: <table> <thead> <tr> <th>Decorator</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>@PathParam</td> <td>Parameter in requested URL path </td> </tr> <tr> <td>@QueryParam</td> <td>Parameter in the query string </td> </tr> <tr> <td>@FormParam</td> <td>Parameter in an HTML form </td> </tr> <tr> <td>@HeaderParam</td> <td>Parameter in the request header</td> </tr> <tr> <td>@CookieParam</td> <td>Parameter in a cookie </td> </tr> <tr> <td>@FileParam</td> <td>A File in a multipart form </td> </tr> <tr> <td>@FilesParam</td> <td>An array of Files in a multipart form </td> </tr> <tr> <td>@Param</td> <td>Parameter in the query string or in an HTML form</td> </tr> </tbody> </table> Some examples: <pre><code class="lang-typescript">@Path("/sample") class Sample { @GET test(@QueryParam("limit") limit:number, @QueryParam("skip") skip:number) { //... // GET http://domain/sample?limit=5&skip=10 } @POST test(@FormParam("name") name:string) { //... // POST http://domain/sample // body: name=joe } @POST @Path("upload") testUploadFile( @FileParam("myFile") file: Express.Multer.File, @FormParam("myField") myField: string) { //... /* POST http://domain/sample/upload Content-Type: multipart/form-data; boundary=AaB03x --AaB03x Content-Disposition: form-data; name="myField" Field Value --AaB03x Content-Disposition: form-data; name="myFile"; filename="file1.txt" Content-Type: text/plain ... contents of file1.txt ... --AaB03x-- */ } } </code></pre> An argument that has no decorator is handled as a json serialized entity in the request body <pre><code class="lang-typescript">@Path("/sample") class Sample { @POST test(user: User) { //... // POST http://domain/sample // body: a json representation of the User object } } </code></pre> <h3 id="service-context">Service Context</h3> A Context object is created to group informations about the current request being handled. This Context can be accessed by service methods. The Context is represented by the <code>ServiceContext</code> class and has the following properties: <table> <thead> <tr> <th>Property</th> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>request</td> <td>express.Request</td> <td>The request object </td> </tr> <tr> <td>response</td> <td>express.Response</td> <td>The response object </td> </tr> <tr> <td>language</td> <td>string</td> <td>The resolved language to be used to handle the current request. </td> </tr> <tr> <td>accept</td> <td>string</td> <td>The preferred media type to be used to respond the current request. </td> </tr> <tr> <td>next</td> <td>express.NextFunction</td> <td>The next function. It can be used to delegate to the next middleware registered the processing of the current request. </td> </tr> </tbody> </table> See <a href="#types-and-languages">Types and languages</a> to know how the language and preferredMedia fields are calculated. The <code>@Context</code> decorator can be used on service method's arguments or on service class properties to bind the argument or the property to the current context object. A Context usage example: <pre><code class="lang-typescript"> @Path("context") class TestService { @Context context: ServiceContext; @GET sayHello() { switch (this.context.language) { case "en": return "Hello"; case "pt": return "Olá"; } return "Hello"; } } </code></pre> We can use the decorator on method arguments too: <pre><code class="lang-typescript"> @Path("context") class TestService { @GET sayHello(@Context context: ServiceContext) { switch (context.language) { case "en": return "Hello"; case "pt": return "Olá"; } return "Hello"; } } </code></pre> You can use, also, one of the other decorators to access directly one of the Context property. It is a kind of suggar syntax. <ul> <li>@ContextRequest: To access ServiceContext.request</li> <li>@ContextResponse: To access ServiceContext.response</li> <li>@ContextNext: To access ServiceContext.next</li> <li>@ContextLanguage: To access ServiceContext.language</li> <li>@ContextAccept: To access ServiceContext.accept</li> </ul> <pre><code class="lang-typescript"> @Path("context") class TestService { @GET sayHello(@ContextLanguage language: string) { switch (language) { case "en": return "Hello"; case "pt": return "Olá"; } return "Hello"; } } </code></pre> <h3 id="service-return">Service Return</h3> This library can receive the return of your service method and handle the serialization of the response as long as handle the correct content type of your result and the response status codes to be sent. When a primitive type is returned by a service method, it is sent as a plain text into the response body. <pre><code class="lang-typescript">@GET sayHello(): string { return "Hello"; } </code></pre> The response will contains only the String <code>Hello</code> as a plain text When an object is returned, it is sent as a json serialized string into the response body. <pre><code class="lang-typescript">@GET @Path(":id") getPerson(@PathParam(":id") id: number): Person { return new Person(id); } </code></pre> The response will contains the person json serialization (ex: <code>{id: 123}</code>. The response will have a <code>application/json</code> context type. When the method returns nothing, an empty body is sent withh a <code>204</code> status code. <pre><code class="lang-typescript">@POST test(myObject: MyClass): void { //... } </code></pre> We provide also, some special types to inform that a reference to a resource is returned and that the server should handle it properly. <table> <thead> <tr> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>NewResource</td> <td>Inform that a new resource was created. Server will add a Location header and set status to 201 </td> </tr> <tr> <td>RequestAccepted</td> <td>Inform that the request was accepted but is not completed. A Location header should inform the location where the user can monitor his request processing status. Server will set the status to 202 </td> </tr> <tr> <td>MovedPermanently</td> <td>Inform that the resource has permanently moved to a new location, and that future references should use a new URI with their requests. Server will set the status to 301 </td> </tr> <tr> <td>MovedTemporarily</td> <td>Inform that the resource has temporarily moved to another location, but that future references should still use the original URI to access the resource. Server will set the status to 302 </td> </tr> </tbody> </table> <pre><code class="lang-typescript">import {Return} from "typescript-rest"; @Path("test") class TestService { @POST test(myObject: MyClass, @ContextRequest request: express.Request): Return.NewResource { //... return new Return.NewResource(req.url + "/" + generatedId); } } </code></pre> The server will return an empty body with a <code>201</code> status code and a <code>Location</code> header pointing to the URL of the created resource. <h4 id="asynchronous-services">Asynchronous services</h4> The above section shows how the types returned are handled by the Server. However, all the previous examples are working synchronously. The recommended way is to work asynchronously, for a better performance. To work asynchronously, you can return a <code>Promise</code> on your service method. The above rules to handle return types applies to the returned promise resolved value. Some examples: <pre><code class="lang-typescript">import {Return} from "typescript-rest"; @Path("async") class TestService { @POST test(myObject: MyClass, @ContextRequest request: express.Request): Promise<Return.NewResource> { return new Promise<Return.NewResource>(function(resolve, reject){ //... resolve(new Return.NewResource(req.url + "/" + generatedId)); }); } @GET testGet() { return new Promise<MyClass>(function(resolve, reject){ //... resolve(new MyClass()); }); } } </code></pre> It is important to observe that you can inform your return type explicitly or not, as you can see in the above example. <h3 id="errors">Errors</h3> This library provide some Error classes to map the problems that you may want to report to your clients. <table> <thead> <tr> <th>Type</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>BadRequestError</td> <td>Used to report errors with status code 400. </td> </tr> <tr> <td>UnauthorizedError</td> <td>Used to report errors with status code 401. </td> </tr> <tr> <td>ForbidenError</td> <td>Used to report errors with status code 403. </td> </tr> <tr> <td>NotFoundError</td> <td>Used to report errors with status code 404. </td> </tr> <tr> <td>MethodNotAllowedError</td> <td>Used to report errors with status code 405. </td> </tr> <tr> <td>NotAcceptableError</td> <td>Used to report errors with status code 406. </td> </tr> <tr> <td>ConflictError</td> <td>Used to report errors with status code 409. </td> </tr> <tr> <td>InternalServerError</td> <td>Used to report errors with status code 500. </td> </tr> <tr> <td>NotImplementedError</td> <td>Used to report errors with status code 501. </td> </tr> </tbody> </table> If you throw any of these errors on a service method, the server you log the problem and send a response with the appropriate status code an the error message on its body. <pre><code class="lang-typescript">import {Errors} from "typescript-rest"; @Path("async") class TestService { @GET @Path("test1") testGet() { return new Promise<MyClass>(function(resolve, reject){ //... throw new Errors.NotImplementedError("This operation is not available yet"); }); } @GET @Path("test2") testGet2() { return new Promise<MyClass>(function(resolve, reject){ //... reject(new Errors.NotImplementedError("This operation is not available yet")); }); } @GET @Path("test3") testGet3() { throw new Errors.NotImplementedError("This operation is not available yet"); } } </code></pre> All the three operations above will return a response with status code <code>501</code> and a message on the body <code>This operation is not available yet</code> If you want to create a custom error that report your own status code, just extend the base class <code>HttpError</code>. <pre><code class="lang-typescript">import {HttpError} from "typescript-rest"; class MyOwnError extends HttpError { static myNoSenseStatusCode: number = 999; constructor(message?: string) { super("MyOwnError", MyOwnError.myNoSenseStatusCode, message); } } </code></pre> <h3 id="types-and-languages">Types and languages</h3> It is possible to use decorators to inform the server which languages or mime types are supported by each service method. These decorators can be used on the service class or on a service method (or both). The following decorators are available: <table> <thead> <tr> <th>Decorator</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>AcceptLanguage</td> <td>Tell the <a href="classes/_server_.server.html">Server</a> that a class or a method should only accept requests from clients that accepts one of the supported languages. </td> </tr> <tr> <td>Accept</td> <td>Tell the <a href="classes/_server_.server.html">Server</a> that a class or a method should only accept requests from clients that accepts one of the supported mime types. </td> </tr> </tbody> </table> See some examples: <pre><code class="lang-typescript">@Path("test") @AcceptLanguage("en", "pt-BR") class TestAcceptService { @GET testLanguage(@ContextLanguage language: string): string { if (language === 'en') { return "accepted"; } return "aceito"; } } </code></pre> In the above example, we declare that only <code>English</code> and <code>Brazilian Portuguese</code> are supported. The order here is important. That declaration says that our first language is <code>English</code>. So, if nothing was specified by the request, or if these two languages has the same weight on the resquest <code>Accept-Language</code> header, <code>English</code> will be the choice. If the request specifies an <code>Accept-Language</code> header, we will choose the language that best fit the header value, considering the list of possible values declared on <code>@AcceptLanguage</code> decorator. If none of our possibilities is good for the <code>Accept-Language</code> header in the request, the server throws a <code>NotAcceptableError</code> and returns a <code>406</code> status code for the client. You can decorate methods too, like: <pre><code class="lang-typescript">@Path("test") @AcceptLanguage("en", "pt-BR") class TestAcceptService { @GET @AcceptLanguage("fr") testLanguage(@ContextLanguage language: string): string { // ... } } </code></pre> On the above example, the list of accepted languages will be <code>["en", "pt-BR", "fr"]</code>, in that order. The <code>@Accept</code> decorator works exaclty like <code>@AcceptLanguage</code>, but it inform the server about the mime type that a service can provide. It uses the <code>Accept</code> header in the request to decide about the preferred media to use. <pre><code class="lang-typescript">@Path("test") @Accept("application/json") class TestAcceptService { @GET testType(@ContextAccept accept: string): string { //... } } </code></pre> </div> </div> <div class="col-4 col-menu menu-sticky-wrap menu-highlight"> <nav class="tsd-navigation primary"> <ul> <li class="globals "> <a href="globals.html">Globals</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_decorators_.html">"decorators"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_es5_compat_.html">"es5-compat"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_metadata_.html">"metadata"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_server_.html">"server"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_server_container_.html">"server-container"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_server_errors_.html">"server-errors"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_server_return_.html">"server-return"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_server_types_.html">"server-types"</a> </li> <li class=" tsd-kind-external-module"> <a href="modules/_typescript_rest_.html">"typescript-rest"</a> </li> </ul> </nav> <nav class="tsd-navigation secondary menu-sticky"> <ul class="before-current"> </ul> </nav> </div> </div> </div> <footer class="with-border-bottom"> <div class="container"> <h2>Legend</h2> <div class="tsd-legend-group"> <ul class="tsd-legend"> <li class="tsd-kind-module">Module</li> <li class="tsd-kind-object-literal">Object literal</li> <li class="tsd-kind-variable">Variable</li> <li class="tsd-kind-function">Function</li> <li class="tsd-kind-function tsd-has-type-parameter">Function with type parameter</li> <li class="tsd-kind-index-signature">Index signature</li> <li class="tsd-kind-type-alias">Type alias</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-enum">Enumeration</li> <li class="tsd-kind-enum-member">Enumeration member</li> <li class="tsd-kind-property tsd-parent-kind-enum">Property</li> <li class="tsd-kind-method tsd-parent-kind-enum">Method</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-interface">Interface</li> <li class="tsd-kind-interface tsd-has-type-parameter">Interface with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-interface">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-interface">Property</li> <li class="tsd-kind-method tsd-parent-kind-interface">Method</li> <li class="tsd-kind-index-signature tsd-parent-kind-interface">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-class">Class</li> <li class="tsd-kind-class tsd-has-type-parameter">Class with type parameter</li> <li class="tsd-kind-constructor tsd-parent-kind-class">Constructor</li> <li class="tsd-kind-property tsd-parent-kind-class">Property</li> <li class="tsd-kind-method tsd-parent-kind-class">Method</li> <li class="tsd-kind-accessor tsd-parent-kind-class">Accessor</li> <li class="tsd-kind-index-signature tsd-parent-kind-class">Index signature</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited">Inherited constructor</li> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited">Inherited property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited">Inherited method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited">Inherited accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected">Protected property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected">Protected method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected">Protected accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-private">Private property</li> <li class="tsd-kind-method tsd-parent-kind-class tsd-is-private">Private method</li> <li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private">Private accessor</li> </ul> <ul class="tsd-legend"> <li class="tsd-kind-property tsd-parent-kind-class tsd-is-static">Static property</li> <li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static">Static method</li> </ul> </div> </div> </footer> <div class="container tsd-generator"> Generated using <a href="http://typedoc.io" target="_blank">TypeDoc</a> </div> <div class="overlay"></div> <script src="assets/js/main.js"></script> <script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script> </body> </html>