Node API

Moera Node API is a JSON-based REST API. See introduction to Node REST API in the Overview section.

Timestamp below is the number of seconds that passed since 01-01-1970 00:00:00 in UTC timezone.

If an error occurs when processing a API request, Result structure is returned instead of the regular response. The structure contains the error code and message, and also the HTTP status code is set accordingly. All error codes are case-insensitive.

An error may occur on different stages of request processing.

If the request URL is unknown, not-found error is returned.
If invalid authentication token or root secret is provided, authentication.invalid error is returned.
If authentication is required, but not provided, authentication.required error is returned.
If request body does not pass validation, a validation error is returned. Look into the chapter on the particular structure for the list of validation errors that correspond to the structure.
If an error occurs while executing the operation, one of the errors listed in the corresponding operation's chapter is returned.
If a configuration error or a software bug occurs, server.misconfiguration error is returned.
If request processing involves a naming server, but it is not available, naming.not-available error is returned.

Authentication scheme, if specified in the request description, may be one of the following:

none or not present - authentication is not required;
root secret - URL parameter secret must be provided with the value equal to the secret value set in the node configuration;
admin - admin token received after signing in must be passed in URL parameter token;
signature - user's access rights are figured out from the name and signature passed in the request body.

Standard permission groups are:

admin - administrator of the node;
owner - owner of the posting, comment etc.

Credentials object

Credentials used to authenticate the administrator of the node.

GET /credentials

Check whether the credentials are initialized already.

Response:: CredentialsCreated
Authentication (read more):: none

POST /credentials

Initialize credentials, if they are not set yet. Note that this operation can be executed without authentication, so this should be done as soon as possible after the node installation. Sign in is not allowed until the credentials are set.

Request body:


                            
                                Credentials

Response:


                            
                                Result

Authentication (read more):

none

Errors:

Code	Description
`credentials.already-created`	credentials are already created

PUT /credentials

Update credentials.

Request body:: Credentials
Response:: Result
Authentication (read more):: admin

Domains object

One instance of Moera node software can serve several virtual nodes. These virtual nodes are called domains and distinguished by the hostname passed in the HTTP request. Each virtual node has node ID, it is used in the database to designate the data that belongs to a particular node. The hostname is mapped to the node ID when the request is processed, using the list of registered domains. If there is no domain with such a name, the special _default_ domain is used.

GET /domains

Get the list of registered domains.

Response:: DomainInfo[]
Authentication (read more):: root secret

GET /domains/{name}

Get information about the domain with the given hostname.

Parameters:

String name - domain name

Response:


                            
                                DomainInfo

Authentication (read more):

root secret

Errors:

Code	Description
`domain.not-found`	there is no domain with the given hostname

POST /domains

Create a new domain with the given hostname. If nodeId is not passed, it is generated automatically.

Request body:


                            
                                DomainInfo

Response:


                            
                                DomainInfo

Authentication (read more):

root secret

Errors:

Code	Description
`domainInfo.name.blank`	the hostname is empty
`domain.already-exists`	the domain with the given hostname already exists

PUT /domains/{name}

Update the domain with the given hostname. If the new hostname is not passed, the old hostname is preserved. (Note that you cannot pass a new name for the default hostname, because it cannot be renamed and _default_ is not a valid hostname. Skip this field if you want to update the default hostname.) If nodeId is not passed, it is generated automatically.

Parameters:

String name - domain hostname

Request body:


                            
                                DomainInfo

Response:


                            
                                DomainInfo

Authentication (read more):

root secret

Errors:

Code	Description
`domain.not-found`	there is no domain with the given hostname
`domain.cannot-rename-default`	cannot change the name of the default domain

DELETE /domains/{name}

Delete the domain with the given hostname. This operation deletes the domain record only, the user's data related to the domain is preserved.

Parameters:

String name - domain name

Response:


                            
                                Result

Authentication (read more):

root secret

Errors:

Code	Description
`domain.not-found`	there is no domain with the given hostname
`domain.cannot-delete-default`	cannot delete the default domain

Postings object

All postings.

POST /postings

Create a new posting from the text given, sign it with the signing key and publish it on the timeline. The heading and the preview of the posting are created automatically, if needed.

Request body:


                            
                                PostingText

Response:


                            
                                PostingInfo

Authentication (read more):

admin

Errors:

Code	Description
`posting.registered-name-not-set`	registered name is not set yet
`posting.signing-key-not-set`	signing key is not set yet

GET /postings/{id}

Get an individual posting.

Parameters:

UUID id - ID of the posting

Response:


                            
                                PostingInfo

Authentication (read more):

none

Errors:

Code	Description
`posting.not-found`	there is no posting with the given ID

GET /postings/features

Get information about supported features of postings.

Response:: PostingFeatures
Authentication (read more):: none

Profile object

The profile - the detailed information about the node's owner, node's purpose etc.

GET /profile

Get the profile.

Response:: ProfileInfo
Authentication (read more):: none or admin

PUT /profile

Update the profile.

Request body:: Profile
Response:: ProfileInfo
Authentication (read more):: admin

Registered Name object

The registered name of the node. Read more about it in the Overview section. Operations with the registered name are performed asynchronously - need to poll the node periodically to get the current status of the operation. Only one operation with the registered name may be performed by the node at any moment.

GET /registered-name

Get the registered name of the node. Admin user receives also the current status of the latest operation with the registered name.

Response:: RegisteredNameInfo
Authentication (read more):: none or admin

POST /registered-name

Register a new name for the node. The corresponding signing key is generated automatically and stored at the node. The updating key is generated and returned in the encoded form and in the form of mnemonic (a sequence of English words) that need to be written down and stored securely to be able to perform further operations with the name.

Request body:


                            
                                NameToRegister

Response:


                            
                                RegisteredNameSecret

Authentication (read more):

admin

Errors:

Code	Description
`naming.operation-pending`	another operation with the registered name is pending currently

PUT /registered-name

Update the registered name of the node. May be used to assign an already-registered name to the node (the corresponding signing key is generated automatically and stored at the node), or to prolong the name. The secret or mnemonic of the updating key must be provided for this operation.

Request body:


                            
                                RegisteredNameSecret

Response:


                            
                                Result

Authentication (read more):

admin

Errors:

Code	Description
`naming.operation-pending`	another operation with the registered name is pending currently
`registeredNameSecret.empty`	the registered name secret or mnemonic are not provided
`registered-name.name-absent`	the registered name/generation is not provided and not known by the node
`registered-name.`	various errors returned by naming server (see the list)

DELETE /registered-name

Delete all the information related to the registered name (including the signing key) from the node. The name record on the naming server is not touched.

Response:


                            
                                Result

Authentication (read more):

admin

Errors:

Code	Description
`naming.operation-pending`	another operation with the registered name is pending currently

Timeline object

Timeline - all postings that user is permitted to read. The postings are sorted by moment, descending.

GET /timeline

Get general information about the timeline.

Response:: TimelineInfo[]
Authentication (read more):: none

GET /timeline/postings

Get a slice of the timeline, delimited by before or after moments (but not both) and the given limit. If neither before nor after are provided, the latest postings are returned. The node may decide to return less postings than the given limit. The postings are always sorted by moment, descending.

Parameters:

int before - filter postings posted at or before this moment

int after - filter postings posted strongly after this moment

int limit - maximum number of postings returned

Response:


                            
                                TimelineSliceInfo

Authentication (read more):

none

Errors:

Code	Description
`timeline.before-after-exclusive`	before and after parameters are not allowed together

Tokens object

The authentication token. Read more about token-base authentication in the Overview section.

GET /tokens/{token}

Get information about the token.

Parameters:: String token - the token
Response:: TokenInfo
Authentication (read more):: none

POST /tokens

Request body:


                            
                                Credentials

Response:


                            
                                TokenCreated

Authentication (read more):

none

Errors:

Code	Description
`credentials.not-created`	credentials are not created yet
`credentials.login-incorrect`	login or password is incorrect

Who Am I object

Brief information about the node.

GET /whoami

Get brief information about the node.

Response:: WhoAmI
Authentication (read more):: none

Structures

Choice

Type	Name	Description
`String`	`value`
`String`	`title`	user-readable title for the value

Credentials

Type	Name	Description
`String`	`login`
`String`	`password`

Validation errors:

Code	Description
`credentials.login.blank`	the login is empty
`credentials.password.blank`	the password is empty

CredentialsCreated

Type	Name	Description
`boolean`	`created`	`true` if the credentials are initialized already, `false` otherwise

DomainInfo

Type	Name	Description
`String`	`name`	domain's hostname or `_default_` for the default domain
`UUID`	`nodeId`	domain's node ID

Validation errors:

Code	Description
`domainInfo.name.blank`	the domain name is empty
`domainInfo.name.wrong-hostname`	the domain name is not a valid hostname
`domainInfo.nodeId.wrong-uuid`	the node ID is not a valid UUID

NameToRegister

Type	Name	Description
`String`	`name`

Validation errors:

Code	Description
`nameToRegister.name.blank`	the name is empty
`nameToRegister.name.invalid`	the name is reserved, too long or contains invalid characters

PostingFeatures

Type	Name	Description
`Choice[]`	`sourceFormats`	List of source text formats the node understands. The well-known values are: `plain-text` - plain text with newlines and paragraphs delimited by empty line; `html` - HTML-formatted text, the node may allow only limited set of tags; `markdown` - text in Markdown format.

PostingInfo

Type	Name	Description
`UUID`	`id`
`String`	`ownerName`	registered name of the posting's owner
`int`	`ownerGeneration`	registered name generation of the posting's owner
`String`	`bodyPreviewHtml`	preview of the posting's body (HTML), may be absent
`byte[]`	`bodySrcHash`	hash of the source text of the posting
`String`	`bodySrcFormat`	format of the source text of the posting, the list of available formats is returned in `PostingFeatures`
`String`	`bodyHtml`	body of the posting (HTML)
`String`	`heading`	heading of the posting
`timestamp`	`createdAt`	posting creation timestamp - the real time when the posting was created
`timestamp`	`publishedAt`	posting publication timestamp - the time the posting is published under at the timeline
`byte[]`	`signature`	the posting's owner signature (the fingerprint see below)
`int`	`moment`

Fingerprint (read more):

Type	Value
`String`	`ownerName`
`int`	`ownerGeneration`
`byte[]`	`bodySrcHash`
`String`	`bodySrcFormat`
`String`	`bodyHtml`
`int`	`createdAt`

PostingText

Type	Name	Description
`String`	`bodySrc`	the source text of the posting
`String`	`bodySrcFormat`	format of the source text of the posting, `plain-text` by default; the list of available formats is returned in `PostingFeatures`
`String`	`bodyHtml`	body of the posting (HTML), may be absent
`timestamp`	`publishAt`	posting publication timestamp, the current timestamp by default

Validation errors:

Code	Description
`postingText.bodySrc.blank`	body text is empty
`postingText.bodySrc.wrong-size`	body text is too long
`postingText.bodySrcFormat.unknown`	unknown body text format
`postingText.bodyHtml.wrong-size`	body HTML is too long

Profile

Type	Name	Description
`String`	`fullName`	node owner's full name
`String`	`gender`	node owners's gender
`String`	`email`	node owner's E-mail address

Validation errors:

Code	Description
`profile.fullName.wrong-size`	the full name is too long
`profile.gender.wrong-size`	the gender string is too long
`profile.email.wrong-email`	the E-mail is not a well-formed E-mail address

ProfileInfo

Type	Name	Description
`String`	`fullName`	node owner's full name
`String`	`gender`	node owners's gender
`String`	`email`	node owner's E-mail address
`String -> String[]`	`operations`	list of the supported operations (see below) and the corresponding access hints

Operations (read more):

Name	Description
`edit`	change the profile

RegisteredNameInfo

Type	Name	Description
`String`	`name`
`int`	`generation`
`OperationStatus`	`operationStatus`	status of the latest operation with the registered name
`timestamp`	`operationStatusUpdated`	the last time the operation status was updated
`String`	`operationErrorCode`	if the operation with the registered name was failed, the code of the failure
`String`	`operationErrorMessage`	if the operation with the registered name was failed, the human-readable description of the failure
`String -> String[]`	`operations`	list of the supported operations (see below) and the corresponding access hints

Operations (read more):

Name	Description
`manage`	any modification of the registered name, prolonging it etc.

RegisteredNameSecret

Type	Name	Description
`String`	`name`
`int`	`generation`
`String[]`	`mnemonic`	human-friendly mnemonic of the updating key
`String`	`secret`	base64-encoded secret of the updating key

Result

Type	Name	Description
`String`	`errorCode`	error code
`String`	`message`	human-readable error message

TimelineInfo

Type	Name	Description
`String -> String[]`	`operations`	list of the supported operations (see below) and the corresponding access hints

Operations (read more):

Name	Description
`add`	add postings to the timeline

TimelineSliceInfo

Type	Name	Description
`int`	`before`	the slice contains all postings before this moment, inclusive. May be the far future.
`int`	`after`	the slice contains all postings after this moment, exclusive. May be the far past.
`PostingInfo[]`	`postings`	the postings

TokenCreated

Type	Name	Description
`String`	`token`	the token
`String[]`	`permissions`	The list of permission groups assigned to the token.

TokenInfo

Type	Name	Description
`String`	`token`	the token
`boolean`	`valid`	`true` if the token is valid, `false` otherwise.
`String[]`	`permissions`	The list of permission groups assigned to the token. See also the list of standard permission groups.

WhoAmI

Type	Name	Description
`String`	`registeredName`
`int`	`registeredNameGeneration`

Enums

OperationStatus

This enum is used to designate the operation status both by the naming server and by the node.

Value	Description
`WAITING`	operation is waiting to be sent to the naming server
`ADDED`	operation was accepted by the naming server
`STARTED`	the naming server started to proceed the operation
`SUCCEEDED`	operation completed successfully
`FAILED`	operation failed
`UNKNOWN`	operation status is unknown

HTTP status codes

Code	Description
`200`	No error.
`400`	Validation of the request body failed.
`401`	Invalid authentication token or root secret.
`403`	Authentication required, but not provided.
`404`	Unrecognized request or object not found.
`409`	Operation failed.
`500`	The node configured incorrectly or a bug in the node software; naming service not available.