@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:

1npm install --save @egomobile/api-utils

Usage

Quick examples

Build API responses

1import createServer, { query, params } from "@egomobile/http-server";
2import { apiResponse, parseListQuery } from "@egomobile/api-utils";
3
4const app = createServer();
5
6app.get("/users", [query(), parseListQuery()], async (request, response) => {
7  // load all users into 'allUsers'
8
9  // use request.listQuery, created by middleware of parseListQuery(),
10  // to select items inside data source of 'allUsers'
11  // and save it to 'selectedUsers'
12
13  apiResponse(request, response)
14    .withList({
15      limit: request.listQuery!.limit,
16      offset: request.listQuery!.offset,
17      totalCount: allUsers.length,
18
19      items: selectedUsers,
20    }) // set list for 'data' prop
21    .send(); // write all data to client
22});
23
24app.get(params("/users/:id"), async (request, response) => {
25  // load user with :id into 'user'
26
27  apiResponse(request, response)
28    .withData(user) // set value for 'data' prop
29    .addMessage({
30      type: "info",
31      message: "foo",
32    }) // an info message for the user
33    .addMessage({
34      type: "warn",
35      message: "bar",
36      internal: true,
37    }) // a warning message for internal usage
38    .send(); // write all data to client
39});
40
41app.listen().catch(console.error);

Error handling

1import createServer, { json } from "@egomobile/http-server";
2import {
3  handleApiError,
4  handleApiNotFound,
5  handleApiParseError,
6} from "@egomobile/api-utils";
7
8const app = createServer();
9
10// set error handlers
11app.setErrorHandler(handleApiError());
12app.setNotFoundHandler(handleApiNotFound());
13
14app.post(
15  "/",
16  // handle parsing errors for JSON data
17  [json({ onParsingFailed: handleApiParseError() })],
18  async (request, response) => {
19    response.write("OK: " + JSON.stringify(request.body!));
20  }
21);
22
23// ...
24
25app.listen().catch(console.error);

Swagger documentation

1import createServer, {
2  ControllersSwaggerBaseDocument,
3} from "@egomobile/http-server";
4import { loadSwaggerDocumentationSync } from "@egomobile/api-utils";
5
6const app = createServer();
7
8app.controllers({
9  rootDir: __dirname + "/controllers",
10
11  // loads a Swagger base document, with all components
12  // from `swagger` subfolder
13  //
14  // the folder must have the following structure:
15  //
16  // .
17  // ├── swagger
18  // │   ├── index.ts (must export the base document => https://egomobile.github.io/node-http-server/types/ControllersSwaggerBaseDocument.html)
19  // |   |
20  // │   ├── components (contains components => https://swagger.io/specification/#components-object)
21  // |   |   ├── callbacks (optional)
22  // |   |   |   ├── FooCallback.ts (exports a callback with the name `FooCallback` => https://swagger.io/specification/#callback-object)
23  // |   |   ├── examples (optional)
24  // |   |   |   ├── FooExample.ts (exports an example with the name `FooExample` => https://swagger.io/specification/#example-object)
25  // |   |   ├── headers (optional)
26  // |   |   |   ├── FooHeader.ts (exports a header with the name `FooHeader` => https://swagger.io/specification/#header-object)
27  // |   |   ├── links (optional)
28  // |   |   |   ├── FooLink.ts (exports a link with the name `FooLink` => https://swagger.io/specification/#link-object)
29  // |   |   ├── parameters (optional)
30  // |   |   |   ├── FooParameter.ts (exports a parameter with the name `FooParameter` => https://swagger.io/specification/#parameter-object)
31  // |   |   ├── requestBodies (optional)
32  // |   |   |   ├── FooRequest.ts (exports a request body with the name `FooRequest` => https://swagger.io/specification/#request-body-object)
33  // |   |   ├── responses (optional)
34  // |   |   |   ├── FooResponse.ts (exports a response with the name `FooResponse` => https://swagger.io/specification/#response-object)
35  // |   |   ├── schemas (optional)
36  // |   |   |   ├── FooSchema.ts (exports a scheme with the name `FooSchema` => https://swagger.io/specification/#schema-object)
37  // |   |   ├── securitySchemes (optional)
38  // |   |   |   ├── FooSecuritySchema.ts (exports a security scheme with the name `FooSecuritySchema` => https://swagger.io/specification/#security-scheme-object)
39  //
40  swagger: loadSwaggerDocumentationSync({
41    dir: __dirname + "/swagger",
42    ext: ".ts", // include TypeScript files
43  }),
44});
45
46app.listen().catch(console.error);

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

1import type { OpenAPIV3 } from "@egomobile/http-server";
2
3const FooResponse: OpenAPIV3.ResponseObject = {
4  description: "A foo response.",
5  content: {
6    "application/json": {
7      examples: {
8        "Example #1": {
9          value: {
10            success: false,
11            data: null,
12            messages: [
13              {
14                code: 40300,
15                id: "03dcbaa4ef879ece0a0d09eeb5d00e6c",
16                internal: true,
17                message: "Forbidden access",
18                type: "error",
19              },
20            ],
21          },
22        },
23      },
24    },
25  },
26};
27
28export default FooResponse;

The object can be referenced by

1{
2  "$ref": "#/components/responses/FooResponse"
3}

Credits

The module makes use of:

• joi by Sideway Inc.

Documentation

The API documentation can be found here.