Hobb API Server: backend for the Rebus Reader system
To start the regular server: npm start
To start the dev-server (which uses nodemon
to automatically restart): npm run dev-server
The server uses OAuth 2.0 for authorization, with JWT
tokens. The JWT tokens should use the same secret value as defined by the
SECRETORKEY
configuration variable (see below). It should also use the
audience and issuer defined by AUDIENCE
and ISSUER
.
Tokens are passed to the server as bearer tokens. A typical example:
GET /924WWrqtc2dbZMF2NQRiHp/library HTTP/1.1
Host: api.rebus.foundation
Date: Fri, 19 Oct 2018 16:25:55 GMT
Authorization: Bearer <token>
...where <token>
is the JWT token.
Typically only the owner of a resource can access a resource.
Requests without a JWT token will fail with a 401 status code.
Requests with a valid JWT token for access to another user's resources will fail with a 403 status code.
The server follows the ActivityPub API. All objects are represented as Activity Streams 2.0 JSON-LD.
Routes for the API are shown here in URI Template format, with the supported HTTP method.
Retrieve the actor
representation for a user. The {userID}
should match the sub
field in the JWT token.
Retrieve the outbox for the user. This is a collection of all activities performed by the user.
Create a new activity for the user, per the client to server interactions mechanism in ActivityPub.
The new activity's location is returned as the Location
header.
See the Activity types section below for supported activity types.
Retrieve an activity representation for a user.
Get the user's activity inbox. Because we don't support following or receiving messages, it should be identical to the outbox.
A collection of all publications the user has uploaded.
A representation of a publication as a collection of Document objects. Documents are included by reference.
A representation of a Document in a publication.
A collection of collections that belong to the user. Currently includes one collection, the library.
The server can handle the following activity types.
To upload a publication, use an activity with type Create
and object type
reader:Publication
. The publication should include all of its Document
members by value, with their full content.
To note that a user has read a document, use an activity with type Read
and
object type Document
.
The server uses environment variables for configuration.
AUDIENCE
: The expected audience for JWT tokens.DEPLOY_STAGE
: Deployment stage. One ofproduction
,staging
, ordevelopment
.DEV_PASSWORD
: A basic auth password used when in development or staging. Username isadmin
.DOMAIN
: Domain name of the server. If the server is hit with HTTP, redirects to https: plus this domain.ISSUER
: Expected issuer for JWT tokens.NODE_ENV
: Environment variable used by express. Can beproduction
ordevelopment
.SECRETORKEY
: Expected shared secret for JWT tokens.
prefix: message
Where prefix can be any of: build, ci, chore, docs, feat, fix, perf, refactor, revert, style, test.
The other rules are as described here
Code should be written in the Standard style and even if it isn't,
prettier-standard
is run on commit to convert the code into Standard style.
(I don't particularly prefer Standard style over any other variety, but we need a coding style and that one's as good as any other and comes with a bunch of ready-made tools.)