temba 0.7.10 → 0.8.0

package/README.md

@@ -0,0 +1,316 @@
+# Temba
+
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+
+[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)
+
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
+
+**Get a simple MongoDB REST API with zero coding in less than 30 seconds (seriously).**
+
+For developers who need a quick backend for small projects.
+
+Powered by NodeJS, Express and MongoDB.
+
+This project is inspired by the fantastic [json-server](https://github.com/typicode/json-server) project, but instead of a JSON file Temba uses a real database. The goal, however, is the same: Get you started with a REST API very quickly.
+
+## Table of contents
+
+[Temba?](#temba-1)
+
+[Getting Started](#getting-started)
+
+[Usage](#usage)
+
+## Temba?
+
+> _"Temba, at rest"_
+
+A metaphor for the declining of a gift, from the [Star Trek - The Next Generation, episode "Darmok"](https://memory-alpha.fandom.com/wiki/Temba).
+
+In the fictional Tamarian language the word _"Temba"_ means something like _"gift"_.
+
+## Getting Started
+
+Prerequisites you need to have:
+
+- Node, NPM
+- Optional: A MongoDB database, either locally or in the cloud
+
+> Wthout a database, Temba also works. However, then data is kept in memory and flushed every time the server restarts.
+
+### Use `npx`
+
+Create your own Temba server with the following command and you are up and running!
+
+```bash
+npx create-temba-server my-rest-api
+```
+
+With this command you clone the [Temba-starter](https://github.com/bouwe77/temba-starter) repository and install all dependencies.
+
+### Manually adding to an existing app
+
+Alternatively, add Temba to your app manually:
+
+1. `npm i temba`
+
+2. Example code to create a Temba server:
+
+```js
+import temba from ("temba");
+const server = temba.create();
+
+const port = process.env.PORT || 3000;
+server.listen(port, () => {
+  console.log(`Temba is running on port ${port}`);
+});
+```
+
+### Configuration
+
+By passing a config object to the `create` function you can customize Temba's behavior. Refer to the [config settings](#config-settings-overview) below for the various possibilities.
+
+## Usage
+
+### Introduction
+
+Out of the box, Temba gives you a CRUD REST API to any resource name you can think of.
+
+Whether you `GET` either `/people`, `/movies`, `/pokemons`, or whatever, it all returns a `200 OK` with a `[]` JSON response. As soon as you `POST` a new resource, followed by a `GET` of that resource, the new resource will be returned. You can also `DELETE`, or `PUT` resources by its ID.
+
+For every resource (`movies` is just an example), Temba supports the following requests:
+
+- `GET /movies` - Get all movies
+- `GET /movies/:id` - Get a movie by its ID
+- `POST /movies` - Create a new movie
+- `PUT /movies/:id` - Update (fully replace) a movie by its ID
+- `DELETE /movies` - Delete all movies
+- `DELETE /movies/:id` - Delete a movie by its ID
+
+### Supported HTTP methods
+
+The HTTP methods that are supported are `GET`, `POST`, `PUT` and `DELETE`. For any other HTTP method a `405 Method Not Allowed` response will be returned.
+
+On the root URI (e.g. http://localhost:8080/) only a `GET` request is supported, which shows you a message indicating the API is working. All other HTTP methods on the root URI return a `405 Method Not Allowed` response.
+
+### MongoDB
+
+When starting Temba, you can send your requests to it immediately. However, then the data resides in memory and is flushed as soon as the server restarts. To persist your data, provide the `connectionString` config setting for your MongoDB database:
+
+```js
+const config = {
+  connectionString: 'mongodb://localhost:27017',
+}
+const server = temba.create(config)
+```
+
+For every resource you use in your requests, a collection is created in the database. However, not until you actually store (create) a resource with a `POST`.
+
+### Allowing specific resources only
+
+If you only want to allow specific resource names, configure them by providing a `resourceNames` key in the config object when creating the Temba server:
+
+```js
+const config = { resourceNames: ['movies', 'actors'] }
+const server = temba.create(config)
+```
+
+Requests on these resources only give a `404 Not Found` if the ID does not exist. Requests on any other resource will always return a `404 Not Found`.
+
+### JSON
+
+Temba only supports JSON. If you send a request with invalid formatted JSON, a `400 Bad Request` response is returned.
+
+When sending JSON data (`POST` and `PUT` requests), adding a `Content-Type: application/json` header is required.
+
+IDs are auto generated when creating resources. IDs in the JSON request body are ignored.
+
+### Static assets
+
+If you want to host static assets next to the REST API, configure the `staticFolder`:
+
+```js
+const config = { staticFolder: 'build' }
+const server = temba.create(config)
+```
+
+This way, you could create a REST API, and the web app consuming it, in one project.
+
+However, to avoid possible conflicts between the API resources and the web app routes you might want to add an `apiPrefix` to the REST API:
+
+### REST URIs prefixes
+
+With the `apiPrefix` config setting, all REST resources get an extra path segment in front of them. If the `apiPrefix` is `'api'`, then `/movies/12345` becomes `/api/movies/12345`:
+
+```js
+const config = { apiPrefix: 'api' }
+const server = temba.create(config)
+```
+
+After configuring the `apiPrefix`, requests to the root URL will either return a `404 Not Found` or a `405 Method Not Allowed`, depending on the HTTP method.
+
+If you have configured both an `apiPrefix` and a `staticFolder`, a `GET` on the root URL will return the `index.html` in the `staticFolder`, if there is one.
+
+### Request body validation or mutation
+
+Temba does not validate request bodies.
+
+This means you can store your resources in any format you like. So creating the following two (very different) _movies_ is perfectly fine:
+
+```
+POST /movies
+{
+    "title": "O Brother, Where Art Thou?",
+    "description": "In the deep south during the 1930s, three escaped convicts search for hidden treasure while a relentless lawman pursues them."
+}
+
+POST /movies
+{
+    "foo": "bar",
+    "baz": "boo"
+}
+```
+
+You can even omit a request body when doing a `POST` or `PUT`. If you don't want that, and build proper validation, use the `requestBodyValidator` config setting:
+
+If you want to do input validation before the `POST` or `PUT` request body is saved to the database, configure Temba as follows:
+
+```js
+const config = {
+  requestBodyValidator: {
+    post: (resourceName, requestBody) {
+      // Validate, or even change the requestBody
+    },
+    put: (resourceName, requestBody) {
+      // Validate, or even change the requestBody
+    }
+  }
+}
+
+const server = temba.create(config)
+```
+
+The `requestBodyValidator` is an object with a `post` and/or `put` field, which contains the callback function you want Temba to call before the JSON is saved to the database.
+
+The callback function receives two arguments: The `resourceName`, which for example is `movies` if you request `POST /movies`. The second argument is the `requestBody`, which is the JSON object in the request body.
+
+Your callback function can return the following things:
+
+- `void`: Temba will just save the request body as-is. An example of this is when you have validated the request body and everything looks fine.
+- `string`: If you return a string Temba will return a `400 Bad Request` with the string as error message.
+- `object`: Return an object if you want to change the request body. Temba will save the returned object instead of the original request body.
+
+Example:
+
+```js
+const config = {
+  requestBodyValidator: {
+    post: (resourceName, requestBody) {
+      // Do not allow Pokemons to be created: 400 Bad Request
+      if (resourceName === 'pokemons') return 'You are not allowed to create new Pokemons'
+
+      // Add a genre to Star Trek films:
+      if (resourceName === 'movies' && requestBody.title.startsWith('Star Trek')) return {...requestBody, genre: 'Science Fiction'}
+
+      // If you end up here, void will be returned, so the request will just be saved.
+    },
+  }
+}
+
+const server = temba.create(config)
+```
+
+### Config settings overview
+
+Configuring Temba is optional, it already works out of the box.
+
+Here is an example of the config settings for Temba, and how you define them:
+
+```js
+const config = {
+  resourceNames: ['movies', 'actors'],
+  connectionString: 'mongodb://localhost:27017',
+  staticFolder: 'build',
+  apiPrefix: 'api',
+  cacheControl: 'public, max-age=300',
+  delay: 500,
+  requestBodyValidator: {
+    post: (resourceName, requestBody) {
+      // Validate, or even change the requestBody
+    },
+    put: (resourceName, requestBody) {
+      // Validate, or even change the requestBody
+    }
+  }
+}
+const server = temba.create(config)
+```
+
+None of the settings are required, and none of them have default values that actually do something. So only the settings you define are used.
+
+These are all the possible settings:
+
+| Config setting         | Description                                                                                |
+| :--------------------- | :----------------------------------------------------------------------------------------- |
+| `resourceNames`        | See [Allowing specific resources only](#allowing-specific-resources-only)                  |
+| `connectionString`     | See [MongoDB](#mongodb)                                                                    |
+| `staticFolder`         | See [Static assets](#static-assets)                                                        |
+| `apiPrefix`            | See [REST URIs prefixes](#rest-uris-prefixes)                                              |
+| `cacheControl`         | The `Cache-control` response header value for each GET request.                            |
+| `delay`                | After processing the request, the delay in milliseconds before the request should be sent. |
+| `requestBodyValidator` | Bla                                                                                        |
+
+## Not supported (yet?)
+
+The following features would be very nice for Temba to support:
+
+### `PATCH` requests
+
+Partial updates using `PATCH`, or other HTTP methods are not (yet?) supported.
+
+### Auth
+
+Temba offers no ways for authentication or authorization (yet?), so if someone knows how to reach the API, they can read and mutate all your data, unless you restrict this in another way.
+
+### Nested parent-child resources
+
+Also nested (parent-child) routes are not supported (yet?), so every URI has the /:resource/:id structure and there is no way to indicate any relation, apart from within the JSON itself perhaps.
+
+### Filtering and sorting
+
+And there is no filtering, sorting, searching, etc. (yet?).
+
+## Under the hood
+
+Temba is built with JavaScript, [Node](https://nodejs.org), [Express](https://expressjs.com/), [Jest](https://jestjs.io/), [Testing Library](https://testing-library.com/), [Supertest](https://www.npmjs.com/package/supertest), and [@rakered/mongo](https://www.npmjs.com/package/@rakered/mongo).
+
+## Which problem does Temba solve?
+
+The problem with JSON file solutions like json-server is the limitations you have when hosting your app, because your data is stored in a file.
+
+For example, hosting json-server on GitHub Pages means your API is essentially readonly, because, although mutations are supported, your data is not really persisted.
+
+And hosting json-server on Heroku does give you persistence, but is not reliable because of its [ephemeral filesystem](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem).
+
+These limitations are of course the whole idea behind json-server, it's for simple mocking and prototyping. But if you want more (persistence wise) and don't mind having a database, you might want to try Temba.
+
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tr>
+    <td align="center"><a href="https://bouwe.io"><img src="https://avatars.githubusercontent.com/u/4126793?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Bouwe K. Westerdijk</b></sub></a><br /><a href="https://github.com/bouwe77/temba/commits?author=bouwe77" title="Code">💻</a> <a href="https://github.com/bouwe77/temba/issues?q=author%3Abouwe77" title="Bug reports">🐛</a> <a href="https://github.com/bouwe77/temba/commits?author=bouwe77" title="Documentation">📖</a> <a href="#ideas-bouwe77" title="Ideas, Planning, & Feedback">🤔</a> <a href="https://github.com/bouwe77/temba/commits?author=bouwe77" title="Tests">⚠️</a></td>
+  </tr>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

package/dist/config/index.js

@@ -23,7 +23,11 @@ var defaultConfig = {
   apiPrefix: '',
   connectionString: null,
   cacheControl: 'no-store',
-  delay: 0
+  delay: 0,
+  requestBodyValidator: {
+    post: function post() {},
+    put: function put() {}
+  }
 };
 
 function initConfig(userConfig) {
@@ -60,5 +64,15 @@ function initConfig(userConfig) {
     config.delay = Number(userConfig.delay);
   }
 
+  if (userConfig.requestBodyValidator) {
+    if (userConfig.requestBodyValidator.post && typeof userConfig.requestBodyValidator.post === 'function') {
+      config.requestBodyValidator.post = userConfig.requestBodyValidator.post;
+    }
+
+    if (userConfig.requestBodyValidator.put && typeof userConfig.requestBodyValidator.put === 'function') {
+      config.requestBodyValidator.put = userConfig.requestBodyValidator.put;
+    }
+  }
+
   return config;
 }

package/dist/errors/index.js

@@ -4,10 +4,18 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.new404NotFoundError = new404NotFoundError;
+exports.new400BadRequestError = new400BadRequestError;
 
 function new404NotFoundError() {
   var message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'Not Found';
   var error = new Error(message);
   error.status = 404;
   return error;
+}
+
+function new400BadRequestError() {
+  var message = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'Bad Request';
+  var error = new Error(message);
+  error.status = 400;
+  return error;
 }

package/dist/routes/get.js

@@ -26,16 +26,17 @@ function createGetRoutes(queries, cacheControl) {
             case 0:
               _context.prev = 0;
               _req$requestInfo = req.requestInfo, resourceName = _req$requestInfo.resourceName, id = _req$requestInfo.id;
+              res.set('Cache-control', cacheControl);
 
               if (!id) {
-                _context.next = 14;
+                _context.next = 13;
                 break;
               }
 
-              _context.next = 5;
+              _context.next = 6;
               return queries.getById(resourceName, id);
 
-            case 5:
+            case 6:
               item = _context.sent;
 
               if (item) {
@@ -44,37 +45,34 @@ function createGetRoutes(queries, cacheControl) {
               }
 
               res.status(404);
-              res.set('Cache-control', cacheControl);
               return _context.abrupt("return", res.send());
 
             case 10:
               res.status(200);
-              res.set('Cache-control', cacheControl);
               res.json(item);
               return _context.abrupt("return", res.send());
 
-            case 14:
-              _context.next = 16;
+            case 13:
+              _context.next = 15;
               return queries.getAll(resourceName);
 
-            case 16:
+            case 15:
               items = _context.sent;
               res.status(200);
-              res.set('Cache-control', cacheControl);
               res.json(items);
               return _context.abrupt("return", res.send());
 
-            case 23:
-              _context.prev = 23;
+            case 21:
+              _context.prev = 21;
               _context.t0 = _context["catch"](0);
               return _context.abrupt("return", next(_context.t0));
 
-            case 26:
+            case 24:
             case "end":
               return _context.stop();
           }
         }
-      }, _callee, null, [[0, 23]]);
+      }, _callee, null, [[0, 21]]);
     }));
     return _handleGetResource.apply(this, arguments);
   }

package/dist/routes/index.js

@@ -30,15 +30,16 @@ function createResourceRouter(queries, _ref) {
   var validateResources = _ref.validateResources,
       resourceNames = _ref.resourceNames,
       apiPrefix = _ref.apiPrefix,
-      cacheControl = _ref.cacheControl;
+      cacheControl = _ref.cacheControl,
+      requestBodyValidator = _ref.requestBodyValidator;
 
   var _createGetRoutes = (0, _get.createGetRoutes)(queries, cacheControl),
       handleGetResource = _createGetRoutes.handleGetResource;
 
-  var _createPostRoutes = (0, _post.createPostRoutes)(queries),
+  var _createPostRoutes = (0, _post.createPostRoutes)(queries, requestBodyValidator),
       handlePost = _createPostRoutes.handlePost;
 
-  var _createPutRoutes = (0, _put.createPutRoutes)(queries),
+  var _createPutRoutes = (0, _put.createPutRoutes)(queries, requestBodyValidator),
       handlePut = _createPutRoutes.handlePut;
 
   var _createDeleteRoutes = (0, _delete.createDeleteRoutes)(queries),

package/dist/routes/post.js

@@ -13,24 +13,27 @@ var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/
 
 var _url = require("url");
 
-function createPostRoutes(queries) {
+var _validator = require("./validator");
+
+function createPostRoutes(queries, requestBodyValidator) {
   function handlePost(_x, _x2, _x3) {
     return _handlePost.apply(this, arguments);
   }
 
   function _handlePost() {
     _handlePost = (0, _asyncToGenerator2["default"])( /*#__PURE__*/_regenerator["default"].mark(function _callee(req, res, next) {
-      var resourceName, newItem;
+      var resourceName, requestBody, newItem;
       return _regenerator["default"].wrap(function _callee$(_context) {
         while (1) {
           switch (_context.prev = _context.next) {
             case 0:
               _context.prev = 0;
               resourceName = req.requestInfo.resourceName;
-              _context.next = 4;
-              return queries.create(resourceName, req.body);
+              requestBody = (0, _validator.validateRequestBody)(requestBodyValidator.post, resourceName, req.body);
+              _context.next = 5;
+              return queries.create(resourceName, requestBody);
 
-            case 4:
+            case 5:
               newItem = _context.sent;
               return _context.abrupt("return", res.set({
                 Location: (0, _url.format)({
@@ -40,17 +43,17 @@ function createPostRoutes(queries) {
                 })
               }).status(201).json(newItem).send());
 
-            case 8:
-              _context.prev = 8;
+            case 9:
+              _context.prev = 9;
               _context.t0 = _context["catch"](0);
               return _context.abrupt("return", next(_context.t0));
 
-            case 11:
+            case 12:
             case "end":
               return _context.stop();
           }
         }
-      }, _callee, null, [[0, 8]]);
+      }, _callee, null, [[0, 9]]);
     }));
     return _handlePost.apply(this, arguments);
   }

package/dist/routes/put.js

@@ -15,18 +15,20 @@ var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/
 
 var _errors = require("../errors");
 
+var _validator = require("./validator");
+
 function ownKeys(object, enumerableOnly) { var keys = Object.keys(object); if (Object.getOwnPropertySymbols) { var symbols = Object.getOwnPropertySymbols(object); if (enumerableOnly) { symbols = symbols.filter(function (sym) { return Object.getOwnPropertyDescriptor(object, sym).enumerable; }); } keys.push.apply(keys, symbols); } return keys; }
 
 function _objectSpread(target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i] != null ? arguments[i] : {}; if (i % 2) { ownKeys(Object(source), true).forEach(function (key) { (0, _defineProperty2["default"])(target, key, source[key]); }); } else if (Object.getOwnPropertyDescriptors) { Object.defineProperties(target, Object.getOwnPropertyDescriptors(source)); } else { ownKeys(Object(source)).forEach(function (key) { Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key)); }); } } return target; }
 
-function createPutRoutes(queries) {
+function createPutRoutes(queries, requestBodyValidator) {
   function handlePut(_x, _x2, _x3) {
     return _handlePut.apply(this, arguments);
   }
 
   function _handlePut() {
     _handlePut = (0, _asyncToGenerator2["default"])( /*#__PURE__*/_regenerator["default"].mark(function _callee(req, res, next) {
-      var _req$requestInfo, resourceName, id, item, updatedItem;
+      var _req$requestInfo, resourceName, id, requestBody, item, updatedItem;
 
       return _regenerator["default"].wrap(function _callee$(_context) {
         while (1) {
@@ -34,49 +36,50 @@ function createPutRoutes(queries) {
             case 0:
               _context.prev = 0;
               _req$requestInfo = req.requestInfo, resourceName = _req$requestInfo.resourceName, id = _req$requestInfo.id;
+              requestBody = (0, _validator.validateRequestBody)(requestBodyValidator.put, resourceName, req.body);
               item = null;
 
               if (!id) {
-                _context.next = 7;
+                _context.next = 8;
                 break;
               }
 
-              _context.next = 6;
+              _context.next = 7;
               return queries.getById(resourceName, id);
 
-            case 6:
+            case 7:
               item = _context.sent;
 
-            case 7:
+            case 8:
               if (item) {
-                _context.next = 9;
+                _context.next = 10;
                 break;
               }
 
               return _context.abrupt("return", next((0, _errors.new404NotFoundError)("ID '".concat(id, "' not found"))));
 
-            case 9:
-              item = _objectSpread(_objectSpread({}, req.body), {}, {
+            case 10:
+              item = _objectSpread(_objectSpread({}, requestBody), {}, {
                 id: id
               });
-              _context.next = 12;
+              _context.next = 13;
               return queries.update(resourceName, item);
 
-            case 12:
+            case 13:
               updatedItem = _context.sent;
               return _context.abrupt("return", res.status(200).json(updatedItem).send());
 
-            case 16:
-              _context.prev = 16;
+            case 17:
+              _context.prev = 17;
               _context.t0 = _context["catch"](0);
               return _context.abrupt("return", next(_context.t0));
 
-            case 19:
+            case 20:
             case "end":
               return _context.stop();
           }
         }
-      }, _callee, null, [[0, 16]]);
+      }, _callee, null, [[0, 17]]);
     }));
     return _handlePut.apply(this, arguments);
   }

package/dist/routes/validator.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.validateRequestBody = validateRequestBody;
+
+var _errors = require("../errors");
+
+function validateRequestBody(validator, resourceName, requestBody) {
+  var validationResult = validator(resourceName, requestBody);
+  if (!validationResult) return requestBody;
+
+  if (typeof validationResult === 'string') {
+    throw (0, _errors.new400BadRequestError)(validationResult);
+  } // The requestBody was replaced by something else.
+
+
+  if (validationResult) requestBody = validationResult;
+  return requestBody;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "temba",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "description": "Get a simple MongoDB REST API with zero coding in less than 30 seconds (seriously).",
   "main": "dist/server.js",
   "scripts": {

package/readme.md

@@ -1,214 +0,0 @@
-# Temba
-
-**Get a simple MongoDB REST API with zero coding in less than 30 seconds (seriously).**
-
-For developers who need a quick backend for small projects.
-
-Powered by NodeJS, Express and MongoDB.
-
-This project is inspired by the fantastic [json-server](https://github.com/typicode/json-server) project, but instead of a JSON file Temba uses a real database. The goal, however, is the same: Get you started with a REST API very quickly.
-
-## Table of contents
-
-[Temba?](#temba-1)
-
-[Getting Started](#getting-started)
-
-[Usage](#usage)
-
-## Temba?
-
-> _"Temba, at rest"_
-
-A metaphor for the declining of a gift, from the [Star Trek - The Next Generation, episode "Darmok"](https://memory-alpha.fandom.com/wiki/Temba).
-
-In the fictional Tamarian language the word _"Temba"_ means something like _"gift"_.
-
-## Getting Started
-
-Prerequisites you need to have:
-
-- Node, NPM
-- Optional: A MongoDB database, either locally or in the cloud
-
-> Wthout a database, Temba also works. However, then data is kept in memory and flushed every time the server restarts.
-
-### Use `npx`
-
-Create your own Temba server with the following command and you are up and running!
-
-```bash
-npx create-temba-server my-rest-api
-```
-
-### Manually adding to an existing app
-
-If you don't want to (or can't) use the starter, add Temba to your app manually:
-
-1. `npm i temba`
-
-2. Example code to create a Temba server:
-
-```js
-import temba from ("temba");
-const server = temba.create();
-
-const port = process.env.PORT || 3000;
-server.listen(port, () => {
-  console.log(`Temba is running on port ${port}`);
-});
-```
-
-### Configuration
-
-By passing a config object to the `create` function you can customize Temba's behavior. Refer to the documentation below for the various possibilities.
-
-## Usage
-
-### Introduction
-
-Out of the box, Temba gives you a CRUD REST API to any resource name you can think of.
-
-Whether you `GET` either `/people`, `/movies`, `/pokemons`, or whatever, it all returns a `200 OK` with a `[]` JSON response. As soon as you `POST` a new resource, followed by a `GET` of that resource, the new resource will be returned. You can also `DELETE`, or `PUT` resources by its ID.
-
-For a every resource, for example `/movies`, Temba supports the following requests:
-
-- `GET /movies` - Get all movies
-- `GET /movies/:id` - Get a movie by its ID
-- `POST /movies` - Create a new movie
-- `PUT /movies/:id` - Update (fully replace) a movie by its ID
-- `DELETE /movies` - Delete all movies
-- `DELETE /movies/:id` - Delete a movie by its ID
-
-### Supported HTTP methods
-
-Requests with an HTTP method that is not supported, so everything but `GET`, `POST`, `PUT` and `DELETE`, a `405 Method Not Allowed` response will be returned.
-
-On the root URI (e.g. http://localhost:8080/) only a `GET` request is supported, which shows you a message indicating the API is working. All other HTTP methods on the root URI return a `405 Method Not Allowed` response.
-
-### MongoDB
-
-When starting Temba, you can send your requests to it immediately. However, then the data resides in memory and is flushed as soon as the server restarts. To persist your data, provide the `connectionString` config setting for your MongoDB database:
-
-```js
-const config = {
-  connectionString: 'mongodb://localhost:27017',
-}
-const server = temba.create(config)
-```
-
-For every resource you use in your requests a collection is created in the database. However, not until you actually store (create) a resource with a `POST`.
-
-### Allowing specific resources only
-
-If you only want to allow specific resource names, configure them by providing a `resourceNames` key in the config object when creating the Temba server:
-
-```js
-const config = { resourceNames: ['movies', 'actors'] }
-const server = temba.create(config)
-```
-
-Requests on these resources only give a `404 Not Found` if the ID does not exist. Requests on any other resource will always return a `404 Not Found`.
-
-### JSON
-
-Temba only supports JSON. If you send a request with invalid formatted JSON, a `400 Bad Request` response is returned.
-
-When sending JSON data (`POST` and `PUT` requests), adding a `Content-Type: application/json` header is required.
-
-IDs are auto generated when creating resources. IDs in the JSON request body are ignored.
-
-### Static assets
-
-If you want to host static assets next to the REST API, configure the `staticFolder`:
-
-```js
-const config = { staticFolder: 'build' }
-const server = temba.create(config)
-```
-
-This way, you could create a REST API, and the web app consuming it, in one project.
-
-However, to avoid possible conflicts between the API resources and the routes in your web app you might want to add an `apiPrefix` to the REST API:
-
-### REST URIs prefixes
-
-With the `apiPrefix` config setting, all REST resources get an extra path segment in front of them. If the `apiPrefix` is `'api'`, then `/movies/12345` becomes `/api/movies/12345`:
-
-```js
-const config = { apiPrefix: 'api' }
-const server = temba.create(config)
-```
-
-After configuring the `apiPrefix`, requests to the root URL will either return a `404 Not Found` or a `405 Method Not Allowed`, depending on the HTTP method.
-
-If you have configured both an `apiPrefix` and a `staticFolder`, a `GET` on the root URL will return the `index.html` in the `staticFolder`, if there is one.
-
-### Config settings overview
-
-Configuring Temba is optional, it already works out of the box. None of the settings are used until you configure them:
-
-```js
-const config = {
-  resourceNames: ['movies', 'actors'],
-  connectionString: 'mongodb://localhost:27017',
-  staticFolder: 'build',
-  apiPrefix: 'api',
-  cacheControl: 'public, max-age=300',
-  delay: 500,
-}
-const server = temba.create(config)
-```
-
-These are all the possible settings:
-
-| Config setting     | Description                                                                                |
-| :----------------- | :----------------------------------------------------------------------------------------- |
-| `resourceNames`    | See [Allowing specific resources only](#allowing-specific-resources-only)                  |
-| `connectionString` | See [MongoDB](#mongodb)                                                                    |
-| `staticFolder`     | See [Static assets](#static-assets)                                                        |
-| `apiPrefix`        | See [REST URIs prefixes](#rest-uris-prefixes)                                              |
-| `cacheControl`     | The `Cache-control` response header value for each GET request.                            |
-| `delay`            | After processing the request, the delay in milliseconds before the request should be sent. |
-
-## Not supported (yet?)
-
-Temba is still very basic. It does not have any model validation, so you can store your resources in any format you like.
-
-So creating the following two (very different) movies is perfectly fine:
-
-```
-POST /movies
-{
-    "title": "O Brother, Where Art Thou?",
-    "description": "In the deep south during the 1930s, three escaped convicts search for hidden treasure while a relentless lawman pursues them."
-}
-
-POST /movies
-{
-    "foo": "bar",
-    "baz": "boo"
-}
-```
-
-Partial updates using `PATCH`, or other HTTP methods are not (yet?) supported.
-
-Temba offers no ways for authentication or authorization (yet?), so if someone knows how to reach the API, they can read and mutate all your data, unless you restrict this in another way.
-
-Also nested (parent-child) routes are not supported (yet?), so every URI has the /:resource/:id structure and there is no way to indicate any relation, apart from within the JSON itself perhaps.
-
-And there is no filtering, sorting, searching, custom routes, etc. (yet?).
-
-## Under the hood
-
-Temba is built with JavaScript, Node, Express, Jest, Testing Library, Supertest, and [@rakered/mongo](https://www.npmjs.com/package/@rakered/mongo).
-
-## Which problem does Temba solve?
-
-The problem with JSON file solutions like json-server is the limitations you have when hosting your app, because your data is stored in a file.
-
-For example, hosting json-server on GitHub Pages means your API is essentially readonly, because, although mutations are supported, your data is not really persisted.
-
-And hosting json-server on Heroku does give you persistence, but is not reliable because of its [ephemeral filesystem](https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem).
-
-These limitations are of course the whole idea behind json-server, it's for simple mocking and prototyping. But if you want more (persistence wise) and don't mind having a database, you might want to try Temba.