@egomobile/api-utils

REST API extensions for @egomobile/http-server module, a very fast alternative to Express.js

Install

Execute the following command from your project folder, where your package.json file is stored:

npm install --save @egomobile/api-utils

Usage

Quick examples

Build API responses

importcreateServer,{query,params}from"@egomobile/http-server";import{apiResponse,parseListQuery}from"@egomobile/api-utils";constapp=createServer();app.get("/users",[query(),parseListQuery()],async(request,response)=>{// load all users into 'allUsers'// use request.listQuery, created by middleware of parseListQuery(),// to select items inside data source of 'allUsers'// and save it to 'selectedUsers'apiResponse(request,response).withList({limit: request.listQuery!.limit,offset: request.listQuery!.offset,totalCount: allUsers.length,items: selectedUsers,})// set list for 'data' prop.send();// write all data to client});app.get(params("/users/:id"),async(request,response)=>{// load user with :id into 'user'apiResponse(request,response).withData(user)// set value for 'data' prop.addMessage({type: "info",message: "foo",})// an info message for the user.addMessage({type: "warn",message: "bar",internal: true,})// a warning message for internal usage.send();// write all data to client});app.listen().catch(console.error);

Error handling

importcreateServer,{json}from"@egomobile/http-server";import{handleApiError,handleApiNotFound,handleApiParseError,}from"@egomobile/api-utils";constapp=createServer();// set error handlersapp.setErrorHandler(handleApiError());app.setNotFoundHandler(handleApiNotFound());app.post("/",// handle parsing errors for JSON data[json({onParsingFailed: handleApiParseError()})],async(request,response)=>{response.write("OK: "+JSON.stringify(request.body!));});// ...app.listen().catch(console.error);

Swagger documentation

importcreateServer,{ControllersSwaggerBaseDocument,}from"@egomobile/http-server";import{loadSwaggerDocumentationSync}from"@egomobile/api-utils";constapp=createServer();app.controllers({rootDir: __dirname+"/controllers",// loads a Swagger base document, with all components// from `swagger` subfolder//// the folder must have the following structure://// .// ├── swagger// │ ├── index.ts (must export the base document => https://egomobile.github.io/node-http-server/types/ControllersSwaggerBaseDocument.html)// | |// │ ├── components (contains components => https://swagger.io/specification/#components-object)// | | ├── callbacks (optional)// | | | ├── FooCallback.ts (exports a callback with the name `FooCallback` => https://swagger.io/specification/#callback-object)// | | ├── examples (optional)// | | | ├── FooExample.ts (exports an example with the name `FooExample` => https://swagger.io/specification/#example-object)// | | ├── headers (optional)// | | | ├── FooHeader.ts (exports a header with the name `FooHeader` => https://swagger.io/specification/#header-object)// | | ├── links (optional)// | | | ├── FooLink.ts (exports a link with the name `FooLink` => https://swagger.io/specification/#link-object)// | | ├── parameters (optional)// | | | ├── FooParameter.ts (exports a parameter with the name `FooParameter` => https://swagger.io/specification/#parameter-object)// | | ├── requestBodies (optional)// | | | ├── FooRequest.ts (exports a request body with the name `FooRequest` => https://swagger.io/specification/#request-body-object)// | | ├── responses (optional)// | | | ├── FooResponse.ts (exports a response with the name `FooResponse` => https://swagger.io/specification/#response-object)// | | ├── schemas (optional)// | | | ├── FooSchema.ts (exports a scheme with the name `FooSchema` => https://swagger.io/specification/#schema-object)// | | ├── securitySchemes (optional)// | | | ├── FooSecuritySchema.ts (exports a security scheme with the name `FooSecuritySchema` => https://swagger.io/specification/#security-scheme-object)//swagger: loadSwaggerDocumentationSync({dir: __dirname+"/swagger",ext: ".ts",// include TypeScript files}),});app.listen().catch(console.error);

Example for an exported object (/swagger/components/responses/FooResponse.ts):

importtype{OpenAPIV3}from"@egomobile/http-server";constFooResponse: OpenAPIV3.ResponseObject={description: "A foo response.",content: {"application/json": {examples: {"Example #1": {value: {success: false,data: null,messages: [{code: 40300,id: "03dcbaa4ef879ece0a0d09eeb5d00e6c",internal: true,message: "Forbidden access",type: "error",},],},},},},},};exportdefaultFooResponse;

The object can be referenced by

{
"$ref": "#/components/responses/FooResponse"
}

Credits

The module makes use of:

• joi by Sideway Inc.

Documentation

The API documentation can be found here.