Common Form library server
Last updated a year ago by kemitchell .
Apache-2.0 · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install commonform-server -g
SYNC missed versions from official npm registry.

Common Form API Server

This package bundles the API server powering, the "back end" for

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. 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.


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


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


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.


GET /publishers

    "publisher": "$publisher",
    "about": "$about"

GET /publishers/{publisher}/projects


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


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


  "email": "$email",
  "about": "$about",
  "password": "$password"

Creates a new publisher.

DELETE /publishers/{publisher}

Authentication: Administrator

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

Authentication: Publisher


{"digest": "$digest"}

PUT /publishers/{publisher} to update

Authentication: Publisher


  "email": "$email",
  "about": "$about",
  "password": "$password"


GET /annotation/{uuid}

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


  • "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.


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.

Current Tags

  • 6.0.0                                ...           latest (a year ago)

36 Versions

  • 6.0.0                                ...           a year ago
  • 5.7.0                                ...           2 years ago
  • 5.6.1                                ...           2 years ago
  • 5.6.0                                ...           2 years ago
  • 5.5.0                                ...           2 years ago
  • 5.4.0                                ...           2 years ago
  • 5.3.0                                ...           2 years ago
  • 5.2.0                                ...           2 years ago
  • 5.1.0                                ...           2 years ago
  • 5.0.0                                ...           2 years ago
  • 4.3.1                                ...           2 years ago
  • 4.3.0                                ...           3 years ago
  • 4.2.1                                ...           4 years ago
  • 4.2.0                                ...           4 years ago
  • 4.1.3                                ...           4 years ago
  • 4.1.2                                ...           4 years ago
  • 4.1.1                                ...           4 years ago
  • 4.1.0                                ...           4 years ago
  • 4.0.2                                ...           4 years ago
  • 4.0.1                                ...           4 years ago
  • 4.0.0                                ...           4 years ago
  • 3.0.1                                ...           4 years ago
  • 3.0.0                                ...           4 years ago
  • 2.1.3                                ...           4 years ago
  • 2.1.2                                ...           4 years ago
  • 2.1.1                                ...           4 years ago
  • 2.1.0                                ...           4 years ago
  • 2.0.1                                ...           4 years ago
  • 2.0.0                                ...           4 years ago
  • 1.0.2                                ...           4 years ago
  • 1.0.1                                ...           4 years ago
  • 0.1.0                                ...           5 years ago
  • 0.0.5                                ...           5 years ago
  • 0.0.4                                ...           5 years ago
  • 0.0.3                                ...           5 years ago
  • 0.0.2                                ...           5 years ago
Maintainers (1)
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 0
Dev Dependencies (11)

Copyright 2014 - 2016 © |