the-fake-backend

Build a fake backend by providing the content of files or JavaScript objects through configurable routes. This service allows the developer to work on a new feature or an existing one using fake data while the real service is in development.

• Installing
• Getting Started
  • Files
• Properties
  • Server
    • Throttlings
    • Pagination
  • Routes
    • Methods
    • Search
    • Overrides
• GraphQL
  • Queries
  • Mutations
• Guides
  • Overriding responses
  • Overriding response content
  • Searching
  • Paginating
  • Dynamic params requests
• Contributing
  • Setup library
  • Example application

Installing

Start by adding the service as a development dependency.

yarn add --dev the-fake-backend

or

npm i --save-dev the-fake-backend

Getting Started

After installing, create a new file that will be responsible for configuring and starting the service.

const { createServer } = require('the-fake-backend');

const server = createServer();

server.routes([
  {
    path: '/example',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        data: 'your-response-data-here',
        // data: (req) => 'your-response-data-here-based-in-request'
      },
    ],
  },
]);

server.listen(8080);

This will create the http://localhost:8080/example endpoint.

Files

You can also use files content as response instead of using the data property.

const { createServer } = require('the-fake-backend');

const server = createServer();

server.routes([
  {
    path: '/cats',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
      },
    ],
  },
  {
    path: '/dogs',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        file: 'data/my/custom/path/to/dogs.txt',
        // file: req => `data/my/custom/path/to/dogs-${req.query.type}.txt`
      },
    ],
  },
]);

server.listen(8080);

The script above generates the following two endpoints.

| Method | Path | Response | | ------ | -------------------------- | -------------------------------------------------- | | GET | http://localhost:8080/cats | The data/cats.json file content | | GET | http://localhost:8080/dogs | The data/my/custom/path/to/dogs.txt file content |

Properties

Server

| Property | Required | Description | | --------------------------- | -------- | ------------------------------------------------------------------------------------------- | | basePath | no | An API context prefix (e.g. /v1) | | middlewares | no | An array of express's middlewares | | proxies | no | The server proxies | | throttlings | no | The server throttlings | | pagination | no | The server pagination setup | | docsRoute | no | The route that will print all the routes as HTML | | definitions | no | The GraphQL definitions. |

Proxies

This property allows to proxy requests.

| Property | Required | Default | Description | | ------------------------ | -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- | | proxies[].name | yes | | The proxy name | | proxies[].host | yes | | The proxy host (e.g.: http://api.dev.com/api) | | proxies[].appendBasePath | No | false | Whether basePath should be appended in target | | proxies[].onProxyReq | No | | A proxy request handler to forward to http-proxy-middleware | | proxies[].onProxyRes | No | | A proxy response handler to forward to http-proxy-middleware |

Throttlings

This property allows responses to be throttled.

| Property | Required | Description | | -------------------- | -------- | ------------------------------------------------- | | throttlings[].name | yes | Custom throttling name | | throttlings[].values | yes | Custom throttling range (array of numbers, in ms) |

Pagination

This property allows routes to be paginated. Response attributes may be printed in response payload (wrapping the given fixture) or headers. Request parameters are read from URL query string.

| Property | Required | Default | Type | Description | | --------------- | -------- | ---------- | ------------------ | ------------------------------------------------------ | | count | no | 'count' | Response attribute | Current page items count | | data | no | 'data' | Response attribute | Current page data | | empty | no | 'empty' | Response attribute | Whether if current page is empty | | first | no | 'first' | Response attribute | Whether if current page is the first one | | headers | no | false | Configuration | Whether response attributes will be present in headers | | last | no | 'last' | Response attribute | Whether if current page is the last one | | next | no | 'next' | Response attribute | Whether if there is a next page | | offsetParameter | no | 'offset' | Request parameter | Requested offset | | page | no | 'page' | Response attribute | Current page | | pageParameter | no | 'page' | Request parameter | Requested page | | pages | no | 'pages' | Response attribute | Pages count | | sizeParameter | no | 'size' | Request parameter | Requested page size | | total | no | 'total' | Response attribute | Total items count |

Routes

| Property | Required | Description | | ---------------------------- | -------- | ------------------------------------------------------------- | | routes[].path | yes | The endpoint address (URI). | | routes[].methods | yes | The route methods, check the method's properties table below. |

Methods

| Property | Type | Required | Default | Description | | ----------------------------------- | ------------------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------- | | methods[].type | string | yes | | HTTP request type | | methods[].code | number | no | 200 | HTTP response status code | | methods[].data | any | (req) => any | no | | HTTP response data. May also be a function with request | | methods[].file | string | (req) => string | no | /data/${req.path} | HTTP response data fixture file (when data is not given). May also be a function with request | | methods[].headers | object | (req) => object | no | | HTTP response headers. May also be a function with request | | methods[].delay | number | no | | HTTP response delay/timeout, in milliseconds | | methods[].search | object | no | | Search parameters | | methods[].pagination | boolean | object | no | false | Whether data is paginated or not. May also be a pagination object | | methods[].overrides | object[] | no | | Custom response scenarios (switchable in CLI) | | methods[].overrideContent | (req, content) => any | no | | A function to override response content before send |

Search

This property allows routes to be searchable.

| Property | Type | Required | Default | Description | | ---------- | -------- | -------- | ---------- | ------------------------------------------ | | parameter | string | yes | 'search' | Query string parameter name | | properties | string[] | yes | | An array of properties to apply the search |

Overrides

This property allows you to create an array of options that will override the current method option.

| Property | Type | Required | Default | Description | | --------------------------- | ------------------------- | -------- | ------- | --------------- | | overrides[].name | string | yes | | Scenario name | | overrides[].code | number | no | 200 | Described above | | overrides[].data | any | (req) => any | no | | Described above | | overrides[].file | string | (req) => string | no | | Described above | | overrides[].headers | object | (req) => object | no | | Described above | | overrides[].delay | number | no | | Described above | | overrides[].search | object | no | | Described above | | overrides[].pagination | boolean | object | no | false | Described above | | overrides[].overrideContent | (req, content) => any | no | | Described above | | overrides[].selected | boolean | no | false | Described above |

GraphQL

We're using apollo-server-express to integrate the GraphQL Server to the the-fake-backend. When you have the definitions property, the server will enable the GraphQL's related endpoints.

| Method | Path | Response | | ------ | ----------------------------- | ------------------------------------------------ | | GET | http://localhost:8080/graphql | The graphical interactive in-browser GraphQL IDE | | POST | http://localhost:8080/graphql | The queries and mutations response |

Queries

The service searches for a JSON file inside the graphl/queries/ folder using the query name, for example, the query below tries to respond with the graphl/queries/getPerson.json file's content.

const { createServer } = require('the-fake-backend');

const serverOptions = {
  definitions: `
    type Person {
      id: String
      name: String
      age: Int
    }

    type Query {
      getPerson(id: String): Person
    }
  `,
};

const server = createServer(serverOptions);

server.listen(8080);

Mutations

The same happens to the mutations, for example, the mutation below tries to respond with the graphl/mutations/createPerson.json file's content.

const { createServer } = require('the-fake-backend');

const serverOptions = {
  definitions: `
    type Person {
      id: String
      name: String
      age: Int
    }

    input PersonInput {
      name: String
      age: Int
    }

    type Mutation {
      createPerson(person: PersonInput): Person
    }
  `,
};

const server = createServer(serverOptions);

server.listen(8080);

The GraphQL's endpoints does not have support for throttlings, proxies, pagination, overridings and search at the moment, we are still working on these features.

Guides

Overriding responses

When a request is made the server will check if the method object contains the overrides property and if there is one override selected through the property selected. If there is an override selected it will be merged with the method object.

Example

const server = createServer({ ... })

server.routes([
  {
    path: '/user',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        file: 'data/my/custom/path/to/client-user.json',
        overrides: [
          {
            name: 'Staff',
            file: 'data/my/custom/path/to/staff-user.json'
          },
          {
            name: 'Super Admin',
            file: 'data/my/custom/path/to/super-admin-user.json'
          },
          {
            name: 'Error 500',
            code: 500
          }
        ]
      }
    ]
  }
]);

// curl -XGET http://localhost:8080/user
// Returns `data/my/custom/path/to/client-user.json` file content.

Press 'o' on terminal and change the URL '/user' with method 'get' with override 'Super Admin'

// curl -XGET http://localhost:8080/user
// Returns `data/my/custom/path/to/super-admin-user.json` file content.

Overriding response content

You can override the response content after all the processing (file/data content, pagination, search, etc.).

Example

// /data/dogs.json
[
  { "id": 1, "name": "Doogo" },
  { "id": 2, "name": "Dogger" },
  { "id": 3, "name": "Dog" },
  { "id": 4, "name": "Doggernaut" },
  { "id": 5, "name": "Dogging" }
]

const { createServer } = require('the-fake-backend');

const server = createServer();

server.routes([
  {
    path: '/dogs',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        overrideContent: (req, content) => ({
          ...content,
          { id: 6, name: 'Bulldog' }
        })
      },
    ],
  },
]);

server.listen(8080);

Searching

You can make an endpoint searchable by declaring the search property in a route.

Example

// /data/dogs.json
[
  { "id": 1, "name": "Doogo" },
  { "id": 2, "name": "Dogger" },
  { "id": 3, "name": "Dog" },
  { "id": 4, "name": "Doggernaut" },
  { "id": 5, "name": "Dogging" }
]

const { createServer } = require('the-fake-backend');

const server = createServer();

server.routes([
  {
    path: '/dogs',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        search: {
          parameter: 'search',
          properties: ['name'],
        },
      },
    ],
  },
]);

server.listen(8080);

You can now make requests to the http://localhost:8080/dogs?search=dogg endpoint. The response will be the data/dogs.json file content filtered.

[
  { "id": 2, "name": "Dogger" },
  { "id": 4, "name": "Doggernaut" },
  { "id": 5, "name": "Dogging" }
]

Paginating

You can make an endpoint paginated by declaring the pagination options in the server (just in case of overriding default values), adding pagination parameter in a route and visiting it with pagination query string parameters.

Route pagination parameter may be a boolean (true) to use global pagination options, or pagination object parts to override global ones.

Note: The pagination is zero-based, so 0 is the first page.

Example

// /data/dogs.json
[
  { "id": 1, "name": "Doogo" },
  { "id": 2, "name": "Dogger" },
  { "id": 3, "name": "Dog" },
  { "id": 4, "name": "Doggernaut" },
  { "id": 5, "name": "Dogging" }
];

const { createServer } = require('the-fake-backend');

const server = createServer(); // if pagination isn't given, default values will be applied

server.routes([
  {
    path: '/dogs',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
        pagination: true,
        // pagination: { headers: true } // only this request will have pagination parameters in response headers
      },
    ],
  },
]);

server.listen(8080);

Then, given a http://localhost:8080/dogs?page=1&size=2 request, the following payload will be returned:

{
  "count": 2,
  "empty": false,
  "first": true,
  "last": false,
  "next": true,
  "page": 1,
  "pages": 3,
  "total": 5,
  "data": [
    { "id": 3, "name": "Dog" },
    { "id": 4, "name": "Doggernaut" }
  ]
}

Note: given http://localhost:8080/dogs?offset=2&size=2 the payload would be the same. Offset attribute has precedence over page.

If headers attribute was set to true in server options (or route pagination options):

const server = createServer({
  pagination: {
    headers: true,
  },
});

Then the metadata attributes would be printed in response headers and the response payload would be the following:

[
  { "id": 3, "name": "Dog" },
  { "id": 4, "name": "Doggernaut" }
]

Dynamic params requests

Just like in Express, route requests may have dynamic params:

const { createServer } = require('the-fake-backend');

const server = createServer();

server.routes([
  {
    path: '/dogs/:id/details',
    methods: [
      {
        type: 'get', // or MethodType.GET with Typescript
      },
    ],
  },
]);

Given a matching HTTP request, e.g. http://localhost:8080/dogs/3/details, the server will search the following fixtures, sorted by precedence:

1. data/dogs/3/details.json
2. data/dogs/:id/details.json

If the request has multiple dynamic params, the precedence is the same, searching the fullly specific fixture, and the fully generic one otherwise.

Contributing

Setup library

1. Clone this repository
2. Run npm install to install dependencies
3. Run npm start to start rollup in watch mode
4. Have fun!

Example application

This repository already have an example application that already install last built version from the-fake-backend before run.

To start this application:

1. Go to example folder
2. Run npm install to install dependencies
3. Run npm start to start example application