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:
-
Install Node.js.
-
Install software:
npm install --global pm2 tcp-log-server commonform-server -
Start a tcp-log-server:
pm2 start tcp-log-server -
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:
-
Redirect port 80 HTTP request to TLS on port 443 and set Strict Transport Security headers.
-
Terminate TLS. https://api.commonform.org uses Let's Encrypt via Certbot.
-
Proxy requests to port 8080.
-
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 /
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
where $depth
is a Number
indicating the depth within which
{digest}
is nested within $digest
, minimum 0
.
Publishers
GET /publishers
GET /publishers/{publisher}/projects
GET /publishers/{publisher}/projects/{project}/publications
where each $edition
is a Reviewers Edition.
GET /publishers/{publisher}/projects/{project}/publications/{edition}
GET /publishers/{publisher}/projects/{project}/publications/current
where $digest
corresponds to the latest non-draft edition.
GET /publishers/{publisher}/projects/{project}/publications/latest
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:
Creates a new publisher.
DELETE /publishers/{publisher}
Authentication: Administrator
POST /publishers/{publisher}/projects/{project}/publications/{edition}
Authentication: Publisher
Body:
PUT /publishers/{publisher} to update
Authentication: Publisher
Body:
Annotations
GET /annotation/{uuid}
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}
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}
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
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.