Starting the docs for the lib/api.js.

2 years ago · 223bef5525
parent bd6e6220b2
commit 223bef5525
1 changed files with 206 additions and 1 deletions
--- a/lib/api.js
+++ b/lib/api.js
@ -1,7 +1,212 @@
-// setting DANGER_ADMIN=1 in the env enables developer and admin without logins
+/*
  __WARNING__: Early documentation. This should be treated as notes to
  remind you of how to use the `api/` handlers with this, rather than
  a full guide.
  This is a convenience library that helps with normalizing JSON API
  requests and responses with [Express.js](https://expressjs.com). The
  `API` class contains useful functions for redirecting, building replies,
  sending back errors, authenticating users, and validating forms. It is
  primarily used in writing `api/` handlers.
  ## How `api/` Handlers Run
  There's a command in `commands/api.js` that runs everything, and contains a lot
  of tricks for Express.js that you should study.  You run this with the `bando.js`
  command runner like this:
  ```shell
  node bando.js api
  ```
  This command then imports all of the files in `api/` recursively, as well as
  the `socket/` handlers, and sets them up to handle requests.  Requests are mapped
  by URL to `api/` by taking the `.js` off the file and using that as the URL. So
  `api/running.js` becomes `/api/running`.
  ## Writing `api/` Handlers
  The code in `api/` is mapped to URLs almost directly, so to create a new
  URL just make a file in that directory.  For example, if you want `/api/running`
  as a check if your server is running, then create the file `api/running.js`.
  The easiest way to make this file is to use the `node bando.js djent` command like this:
  ```shell
  node bando.js djent --template static/djenterator/api.js --output api/running.js
  ```
  This will use the template in `static/djenterator/api.js` to craft a starter file
  for your `api/running.js`.  If you want to change the output you can access
  [http://127.0.0.1:5001/admin/#/djenterator/](http://127.0.0.1:5001/admin/#/djenterator/)
  and visually choose the template to change, and edit the `.json` variables file it uses.
  You should study this template output for all of the things you might need, although most
  of it you'll strip out in this little tutorial.
  ## Handling Requests
  To handle a `GET`, `POST`, or other request you simply create an exported function that
  matches the lowercase version of the name:
  ```javascript
  export const get = async (req, res) => {
    // do you thing here
  }
  ```
  In the example file `api/running.js` you just created with `bando.js djent`
  you should see this function.  Next you'll strip out everything that has
  nothing to do with replying with a status.
  ## Using `class API`
  You create the `API` class using the Express `request` and `response`
  objects in your `api/` handler, then use the methods `.reply()`, `.redirect()`,
  or `.error()` to report status of the HTTP request.  Let's strip down
  your generated `api/running.js` file to the minimum necessary:
  ```javascript
  import logging from '../lib/logging.js';
  import { API } from '../lib/api.js';
  const log = logging.create(import.meta.url);
  export const get = async (req, res) => {
    const api = new API(req, res);
    try {
      api.reply(200, { message: "OK"});
    } catch (error) {
      log.error(error);
      api.error(500, error.message || "Internal Server Error");
    }
  }
  ```
  Here you can see I am only leaving logging, `API`, and returning simple replies
  with `api.reply(200, {message: "OK"))` or a more complex error reply if that fails.
  ## Authenticating Requests
  Authentication for a handler is very simple and mostly done for you:
  ```javascript
  // add this after the above get method
  get.authenticated = true;
  ```
  You "tag" any handlers you want protected with authentication by setting the `authenticated`
  variable on them.  The `commands/api.js` runner then knows to demand authentication before
  running this handler.  When it is run you can then use `API.user` to get at the authenticated
  user.
  ## Form Validation
  Validating forms in a server is very important, as you can't trust that any
  browser actually performed the validation.  The `API` class uses the wonderful
  [Laravel validation rules](https://laravel.com/docs/9.x/validation) via the
  very nice [Validation](https://www.npmjs.com/package/Validator) module by
  [jfstn](https://github.com/jfstn/Validator).  These rules are also the same
  as returned by the `lib/ormish.js:Model.validation` method.  That means you
  can:
  1. Get your Model from `lib/models.js`.
  2. Call `TheModel.validation(rules)` with empty '' for any rules you want filled in based on the database schema.
  3. Pass those rules to `API.validate()` to check inputs match the Model's rules.
  4. Return a `API.validation_error()` when they fail.
  Here's an example taken from the `api/register.js` handler, but stipped down to
  the essentials so it only validates a user form then returns the cleaned up form:
  ```javascript
    import { User, Site, } from "../lib/models.js";
    const rules = User.validation({
      email: '',
      full_name: '',
      initials: 'required|alpha|max:3',
      password_repeat: 'required|same:password',
      password: '',
      tos_agree: 'required|boolean|accepted',
    });
    export const post = async (req, res) => {
      const api = new API(req, res);
      const form = api.validate(rules);
      if(!form._valid) {
        return api.validation_error(res, form);
      } else {
        api.clean_form(form, rules);
        api.reply(200, {clean_user: form});
      }
    }
  ```
  ## A Good Validation Pattern
  Validating forms and input is ver important, but you want to do it in a way that
  doesn't interfere with a user's typing, yet still uses the client-side browser to
  speed up the validation feedback.  There's also the problem that _all_ form validation
  systems seem to need the validation rules in both the backend and frontend of the
  application.
  I've found the best pattern to handle all of these is to "validate on first submit, return
  the rules for later submits."  It works like this:
  1. On the first view of the form do _not_ provide any validation feedback. This removes the annoying noise of fields claiming inputs are wrong when they're simply being worked on.  For example, as someone types their email it's annoying to flash it right/wrong until they're done.
  2. Always validate based on the rules, and even better based on the database schema.
  3. When this first validation fails, return a validation failure _and_ return the rules for the browser to use for later attempts.
  4. The browser then has the rules, shows that there was an error, and can then provide immediate fast feedback to the user and block submits until its correct.
  5. This also places the rules in only one place: the backend, where they're absolutely required.
  ## Client Side Validation
  The validation process I described needs one more component on the client side, which is
  demonstrated in the `client/pages/Registration.svelte` page:
  ```javascript
  const register = async () => {
    let [status, data] = await api.post("/api/register", form);
    if(status === 200) {
      $user.new_registration = true;
      push('/');
    } else {
      form = Object.assign(form, data);
    }
  }
  ```
  The `api.post("/api/register", form)` then uses `API.validation_error` to return an
  error response which contains the errors _and_ validation rules that the browser
  should use.  Remember, the `api.post()` above is from `client/api.js:post` while
  the `API.validation_error` is from this file.
  ___BUG___: Currently `client/pages/Registration.svelte` doesn't demonstrate the other part
  of using `client/api.js:validate` to do more validations in the browser.
  ## Going Further
  Once you get this working that's mostly all there is to writing an `api/` handler in
  The Bandolier.  You'll then want to learn how `lib/ormish.js` and `lib/models.js` works,
  and how to create new UIs in `client/` or `admin/`.  On the client side you'll want to
  study the `client/api.js` which is the counterpart to this module, and look at the
  `client/components/FormField.svelte` plus `client/pages/Registration.svelte` for other
  examples.
 */
 import Validator from 'Validator';
 /*
  Used internally to handle security decisions based on whether someone
  runs the app with `DANGER_ADMIN=1` environment variable set or not.
  Originally I was very loose in how this can be set, with sometimes `DANGER_ADMING=true`
  or `DANGER_ADMIN="1"`, but I've since normalized that it will _only_ work if
  `DANGER_ADMIN==="1"`.
 */
 export const developer_admin = process.env.DANGER_ADMIN === "1";