Newly Potted Mandrakes

    commonform-server

    6.0.0 • Public • Published

    Common Form API Server

    This package bundles the API server powering https://api.commonform.org, the "back end" for https://commonform.org.

    The server stores Common Form objects, publisher information, publications, annotations, and subscriptions. With Mailgun credentials, it also sends e-mail notifications for changes to which publishers subscribe.

    Running a Server

    To run a Common Form API server of your own, using pm2 to manage logging, configuration, and monitoring:

    1. Install Node.js.

    2. Install software:

      npm install --global pm2 tcp-log-server commonform-server
    3. Start a tcp-log-server:

      pm2 start tcp-log-server
    4. Start the Common Form API server, setting an administrator password:

      ADMINISTRATOR_PASSWORD="..." pm2 start commonform-server

    By default, the API server will listen for HTTP requests on port 8080. You should firewall remote connections to 4444 and 8080 and configure NGINX or another reverse proxy to:

    1. Redirect port 80 HTTP request to TLS on port 443 and set Strict Transport Security headers.

    2. Terminate TLS. https://api.commonform.org uses Let's Encrypt via Certbot.

    3. Proxy requests to port 8080.

    4. Set headers for CORS if you need them.

    See commonform-nginx for example configuration.

    API

    The API server serves all data via HTTP 1.1.

    Endpoints are described as RFC 6570 templates. Strings like {digest} are placeholders.

    All served and accepted is JSON. Values like "$label" below are placeholders.

    Access-restricted endpoints require HTTP Basic authentication. Use TLS.

    Service Metadata

    GET /

    {
      "service": "commonform-server",
      "version": "$version"
    }

    Forms

    GET /forms/{digest}

    Serves a Common Form with the given hex-encoded, SHA256 digest, according to commonform-normalize.

    POST /forms

    Authentication: Required

    Body: Common Form object meeting the requirements of commonform-validate.

    GET /forms/{digest}/parents

    [
      {
        "digest": "$digest",
        "depth": "$depth"
      }
    ]

    where $depth is a Number indicating the depth within which {digest} is nested within $digest, minimum 0.

    Publishers

    GET /publishers

    [
      {
        "publisher": "$publisher",
        "about": "$about"
      }
    ]

    GET /publishers/{publisher}/projects

    ["$project_name"]

    GET /publishers/{publisher}/projects/{project}/publications

    ["$edition"]

    where each $edition is a Reviewers Edition.

    GET /publishers/{publisher}/projects/{project}/publications/{edition}

    {"digest": "$digest"}

    GET /publishers/{publisher}/projects/{project}/publications/current

    {"digest": "$digest"}

    where $digest corresponds to the latest non-draft edition.

    GET /publishers/{publisher}/projects/{project}/publications/latest

    {"digest": "$digest"}

    where $digest corresponds to the latest edition, which may be a draft.

    GET /publishers/{publisher}/projects/{project}/publications/{edition}/form

    Redirects to the corresponding /forms/{digest}.

    GET /publishers/{publisher}/projects/{project}/publications/current/form

    Redirects to the corresponding /forms/{digest}.

    GET /publishers/{publisher}/projects/{project}/publications/latest/form

    Redirects to the corresponding /forms/{digest}.

    POST /publishers/{publisher}

    Authentication: administrator:$ADMINISTRATOR_PASSWORD

    Body:

    {
      "email": "$email",
      "about": "$about",
      "password": "$password"
    }

    Creates a new publisher.

    DELETE /publishers/{publisher}

    Authentication: Administrator

    POST /publishers/{publisher}/projects/{project}/publications/{edition}

    Authentication: Publisher

    Body:

    {"digest": "$digest"}

    PUT /publishers/{publisher} to update

    Authentication: Publisher

    Body:

    {
      "email": "$email",
      "about": "$about",
      "password": "$password"
    }

    Annotations

    GET /annotation/{uuid}

    {
      "publisher": "$publisher",
      "form": "$digest",
      "context": "$digest",
      "replyTo": ["$uuid"],
      "text": "$string"
    }

    where:

    • "form" is the form to which the annotation pertains.

    • "context" is the form containing "form" in which the annotation is relevant. "context" equals "form" is the annotation is relevant wherever the form appears.

    • "replyTo" is an array of annotation UUIDs to which this annotation responds, latest first.

    DELETE /annotation/{uuid}

    Delete an annotation.

    Publishers may only delete comments without any replies.

    GET /annotations?context={context}

    [
      {
        "publisher": "$publisher",
        "form": "$digest",
        "context": "$digest",
        "replyTo": ["$uuid"],
        "text": "$string"
      }
    ]

    where {context} is a form digest and each Object in the Array is an annotation to a form in {context} in the context of {context}.

    GET /annotations?context={context}&form={form}

    [
      {
        "publisher": "$publisher",
        "form": "{form}",
        "context": "$digest",
        "replyTo": ["$uuid"],
        "text": "$string"
      }
    ]

    where {context} is a form digest, {form} is the digest of a form within {context}, and each Object in the Array is an annotation to {form} in the context of {context}.

    POST /annotations

    Authentication: Publisher

    {
      "publisher": "$publisher",
      "form": "$digest",
      "context": "$digest",
      "replyTo": ["$uuid"],
      "text": "$string"
    }

    See GET /annotations/{uuid}.

    DELETE /annotation/{uuid}

    Authorization: Publisher

    Indexed Namespaces

    The API server indexes several namespaces used in forms. Except form digests, which are always lower-case, all names are stored and queried without regard to letter case.

    The server only indexes published forms. It does not index forms provided via POST /forms until they are referenced by a request body to POST /publishers/{}/projects/{}/publication/{}.

    Namespace Relations Type That...
    terms definitions forms define term
    terms uses forms use term
    headings forms (same) appear under heading
    headings references forms reference heading
    forms headings (same) appear under heading
    forms publications (same) reference form
    projects publishers (same) have used project name
    digests summarize forms

    Forms are named by digest.

    GET /{namespace}{?prefix}

    List names in {namespace}, optionally limiting to only those beginning with `{prefix}.

    For example: GET /terms?prefix=indem.

    GET /{namespace}/{name}/{relations}{?skip,limit}

    List the relations of a name, optionally limiting the number of results and skipping a given number of initial results.

    Subscriptions

    Publishers can create subscriptions to API objects that trigger e-mail notifications on relevant changes:

    POST Events
    /annotations/{uuid}/subscribers/{subscriber} replies
    /forms/{digest}/subscribers annotations
    /forms/{digest}/subscribers publications
    /publishers/{publisher}/subscribers/{subscriber} publications

    Publishers can GET the same endpoints to check whether they are subscribed, and DELETE them to unsubscribe, all with authentication.

    Keywords

    none

    Install

    npm i commonform-server

    DownloadsWeekly Downloads

    0

    Version

    6.0.0

    License

    Apache-2.0

    Unpacked Size

    303 kB

    Total Files

    108

    Last publish

    Collaborators

    • kemitchell