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