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.
not-found
error is returned.invalid-syntax
error is returned.invalid-argument-value
error is
returned.
authentication.invalid
error is
returned.
authentication.required
error is returned.
server.misconfiguration
error is returned.
naming.not-available
error is returned.
Authentication scheme, if specified in the request description, may be one of the following:
secret
must be provided with the value equal to the secret
value set in the node configuration;
token
;
Standard permission groups are:
admin
- administrator of the node;owner
- owner of the posting, comment etc.Asyncronous operations pending or just finished on the node.
Get status of the asyncronous operation that performs verification of a remote posting signature.
String id
- asynchronous operation ID
RemotePostingVerificationInfo
Credentials used to authenticate the administrator of the node.
Check whether the credentials are initialized already.
CredentialsCreated
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.
Credentials
Result
Code | Description |
---|---|
credentials.already-created |
credentials are already created |
Update credentials.
Credentials
Result
All deleted postings, that are not purged from the database yet.
Get the list of deleted postings, page by page. The node may decide to use smaller page size than the given limit
. The postings are always sorted by the deletion timestamp, descending.
int page
- page number, 0 by default
int limit
- page size (maximum number of postings returned), the default is defined by the node
PostingInfo[]
Code | Description |
---|---|
page.invalid |
page parameter has an invalid value |
limit.invalid |
limit parameter has an invalid value |
Get an individual deleted posting.
String id
- ID of the posting
PostingInfo
Code | Description |
---|---|
posting.not-found |
there is no deleted posting with the given ID |
Restore a posting. A new revision is created with the same content as in the latest revision.
String id
- ID of the posting
PostingInfo
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
All revisions of the deleted posting. This object supports the same requests as Posting Revisions object, but uses /deleted-postings
prefix instead of /postings
.
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 the list of registered domains.
DomainInfo[]
Get information about the domain with the given hostname.
String name
- domain name
DomainInfo
Code | Description |
---|---|
domain.not-found |
there is no domain with the given hostname |
Create a new domain with the given hostname. If nodeId
is not passed, it is generated automatically.
DomainInfo
DomainInfo
Code | Description |
---|---|
domainInfo.name.blank |
the hostname is empty |
domain.already-exists |
the domain with the given hostname already exists |
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.
String name
- domain hostname
DomainInfo
DomainInfo
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 the domain with the given hostname. This operation deletes the domain record only, the user's data related to the domain is preserved.
String name
- domain name
Result
Code | Description |
---|---|
domain.not-found |
there is no domain with the given hostname |
domain.cannot-delete-default |
cannot delete the default domain |
All postings. Each posting may contain one or more revisions, a new revision is created every time the posting is updated. The latest revision is the current one, the previous ones are marked as deleted.
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.
PostingText
PostingInfo
Code | Description |
---|---|
posting.registered-name-not-set |
registered name is not set yet |
posting.signing-key-not-set |
signing key is not set yet |
Update the posting, creating a new revision of it. The text is processed just like in the POST
request.
String id
- ID of the posting
PostingText
PostingInfo
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
posting.registered-name-not-set |
registered name is not set yet |
posting.signing-key-not-set |
signing key is not set yet |
Get an individual posting.
String id
- ID of the posting
String include
- Comma-separated list of additional blocks of information that are needed. The values are: source
- source text of the posting.
PostingInfo
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
Delete the posting. The posting may not be purged from the database immediately, but preserved for some period of time to give a chance to restore it.
String id
- ID of the posting
Result
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
Get information about supported features of postings.
PostingFeatures
All revisions of the posting.
Get all revisions of the posting.
String postingId
- ID of the posting
PostingRevisionInfo[]
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
Get an individual revision of the posting.
String postingId
- ID of the posting
String id
- ID of the revision
PostingRevisionInfo
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
posting-revision.not-found |
there is no revision with the given ID |
Restore a revision of the posting. A new revision is created with the same content as in the given revision.
String postingId
- ID of the posting
String id
- ID of the revision
PostingRevisionInfo
Code | Description |
---|---|
posting.not-found |
there is no posting with the given ID |
posting-revision.not-found |
there is no revision with the given ID |
posting-revision.already-current |
the given revision is already the current one |
The profile - the detailed information about the node's owner, node's purpose etc.
Get the profile.
ProfileInfo
Update the profile.
Profile
ProfileInfo
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 the registered name of the node. Admin user receives also the current status of the latest operation with the registered name.
RegisteredNameInfo
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.
NameToRegister
RegisteredNameSecret
Code | Description |
---|---|
naming.operation-pending |
another operation with the registered name is pending currently |
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.
RegisteredNameSecret
Result
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 is not provided and not known by the node |
registered-name. |
various errors returned by naming server (see the list) |
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.
Result
Code | Description |
---|---|
naming.operation-pending |
another operation with the registered name is pending currently |
Postings located on other nodes.
Verify the signature of the given posting.
String nodeName
- name of the remote node
String id
- ID of the posting on the remote node
AsyncOperationCreated
Verify the signature of the given revision of a posting.
String nodeName
- name of the remote node
String id
- ID of the posting on the remote node
String revisionId
- ID of the posting revision
AsyncOperationCreated
Settings - the node and client settings. The node settings affect the node behavior. Only those settings are accepted that are known by the node, and their values are validated before saving. The node settings metadata can be obtained by request. The client settings are saved without validation and their metadata is built into the client. All client settings must have names starting with client.
to distinguish them from the node ones. By convention, the client name is added to the prefix (client.<client name>.
) to be able to store settings of several different clients at the same time.
Get all node settings, sorted by name. If a setting has not changed its value from the default, it is omitted.
String prefix
- filter settings whose names start with the given prefix, case-sensitive
SettingInfo[]
Get all client settings, sorted by name.
String prefix
- filter settings whose names start with the given prefix, case-sensitive (client.
prefix must be included)
SettingInfo[]
Get all node settings metadata, sorted by name.
String prefix
- filter settings whose names start with the given prefix, case-sensitive
SettingMetaInfo[]
Update the given settings. If the input contains node settings, they are validated and the first validation error is returned, if any. The update is always performed as whole - if there is an error saving any one of the settings in the input, none of them are updated.
SettingInfo[]
Result
Code | Description |
---|---|
setting.deserialization-failed |
setting value deserialization failed |
setting.cannot-convert |
cannot convert value to the setting type |
setting.invalid-value |
invalid value for the setting |
setting.internal |
cannot set value of an internal setting |
setting.unknown |
unknown setting |
Timeline - all postings that user is permitted to read. The postings are sorted by moment, descending.
Get general information about the timeline.
TimelineInfo[]
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.
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
TimelineSliceInfo
Code | Description |
---|---|
timeline.before-after-exclusive |
before and after parameters are not allowed together |
limit.invalid |
limit parameter has an invalid value |
The authentication token. Read more about token-base authentication in the Overview section.
Get information about the token.
Sign in and create a token.
Credentials
TokenCreated
Code | Description |
---|---|
credentials.not-created |
credentials are not created yet |
credentials.login-incorrect |
login or password is incorrect |
Brief information about the node.
Get brief information about the node.
Type | Name | Description |
---|---|---|
String
|
id |
ID of the asyncronous operation that was created |
Type | Name | Description |
---|---|---|
String
|
subject |
plain text |
String
|
text |
HTML |
Type | Name | Description |
---|---|---|
String
|
value |
|
String
|
title |
user-readable title for the value |
Type | Name | Description |
---|---|---|
String
|
login |
|
String
|
password |
Code | Description |
---|---|
credentials.login.blank |
the login is empty |
credentials.password.blank |
the password is empty |
Type | Name | Description |
---|---|---|
boolean
|
created |
true if the credentials are initialized already, false otherwise |
Type | Name | Description |
---|---|---|
String
|
name |
domain's hostname or _default_ for the default domain |
UUID
|
nodeId |
domain's node ID |
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 |
Type | Name | Description |
---|---|---|
String
|
name |
Code | Description |
---|---|
nameToRegister.name.blank |
the name is empty |
nameToRegister.name.invalid |
the name is reserved, too long or contains invalid characters |
Type | Name | Description |
---|---|---|
boolean
|
subjectPresent |
true if new postings are recommended to have a subject, false otherwise |
Choice[]
|
sourceFormats |
List of source text formats the node understands. The well-known values are:
|
Type | Name | Description |
---|---|---|
String
|
id |
|
String
|
revisionId |
ID of the current revision of the posting |
int
|
totalRevisions |
total number of revisions the posting has |
String
|
receiverName |
registered name of the node where the posting was published |
String
|
ownerName |
registered name of the posting's owner |
String
|
bodyPreview |
preview of the posting's body, a string representation of a JSON structure, may be absent |
String
|
bodySrc |
the source text of the posting, a string representation of a JSON structure, may be absent if not requested |
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
|
body |
body of the posting, a string representation of a JSON structure |
String
|
bodyFormat |
format of the body of the posting, may have any value meaningful for the client, including:
|
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 |
timestamp
|
editedAt |
posting editing timestamp - the last time the posting was updated |
timestamp
|
deletedAt |
posting deletion timestamp - the time when the posting was deleted, may be absent |
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
byte[]
|
signature |
the posting's owner signature (the fingerprint see below) |
int
|
moment |
|
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
Name | Description |
---|---|
edit |
edit the posting |
delete |
delete the posting |
revisions |
view the posting's revisions |
Type | Value |
---|---|
String |
receiverName |
String |
ownerName |
byte[] |
bodySrcHash |
String |
bodySrcFormat |
String |
body |
String |
bodyFormat |
int |
createdAt (of the current revision) |
Type | Name | Description |
---|---|---|
String
|
id |
|
String
|
bodyPreview |
preview of the revisions's body, a string representation of a JSON structure, may be absent |
byte[]
|
bodySrcHash |
hash of the source text of the revision |
String
|
bodySrcFormat |
format of the source text of the revision, the list of available formats is returned in PostingFeatures
|
String
|
body |
body of the revision, a string representation of a JSON structure |
String
|
bodyFormat |
format of the body of the revision, see detailed description in PostingInfo .bodyFormat
|
String
|
heading |
heading of the revision |
timestamp
|
createdAt |
revision creation timestamp - the real time when the revision was created |
timestamp
|
publishedAt |
revision publication timestamp - the time the revision is published under at the timeline |
timestamp
|
deletedAt |
revision deletion timestamp - the time when the revision was deleted, may be absent |
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
byte[]
|
signature |
the revision's owner signature (the fingerprint see in PostingInfo )
|
int
|
moment |
Type | Name | Description |
---|---|---|
String
|
bodySrc |
the source text of the posting, a string representation of a JSON structure |
String
|
bodySrcFormat |
format of the source text of the posting, plain-text by default; the list of available formats is returned in PostingFeatures
|
String
|
body |
body of the posting, a string representation of a JSON structure, may be absent |
String
|
bodyFormat |
format of the body of the posting, see detailed description in PostingInfo .bodyFormat
|
timestamp
|
publishAt |
posting publication timestamp, the current timestamp by default |
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.body.wrong-size |
body HTML is too long |
Type | Name | Description |
---|---|---|
String
|
fullName |
node owner's full name |
String
|
gender |
node owners's gender |
String
|
email |
node owner's E-mail address |
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 |
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 |
Name | Description |
---|---|
edit |
change the profile |
Type | Name | Description |
---|---|---|
String
|
name |
|
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 |
Name | Description |
---|---|
manage |
any modification of the registered name, prolonging it etc. |
Type | Name | Description |
---|---|---|
String
|
name |
|
String[]
|
mnemonic |
human-friendly mnemonic of the updating key |
String
|
secret |
base64-encoded secret of the updating key |
Type | Name | Description |
---|---|---|
String
|
id |
asynchronous operation ID |
String
|
nodeName |
|
String
|
postingId |
|
String
|
revisionId |
|
String
|
status |
status of the operation, may be one of:
|
String
|
errorCode |
error code |
String
|
errorMessage |
human-readable error message |
Type | Name | Description |
---|---|---|
String
|
errorCode |
error code |
String
|
message |
human-readable error message |
Type | Name | Description |
---|---|---|
String
|
name |
name of the setting |
String
|
value |
value of the setting |
Type | Name | Description |
---|---|---|
String
|
name |
name of the setting |
String
|
type |
type of the setting, may be one of:
|
String
|
defaultValue |
default value of the setting |
String
|
title |
human-friendly description of the setting |
SettingTypeModifiers
|
modifiers |
additional modifiers that may help to choose a proper UI component for the setting value and to validate the input; meaning of the modifiers depend on the setting type |
Type | Name | Description |
---|---|---|
String
|
min |
(int , Duration ) minimal value |
String
|
max |
(int , Duration ) maximal value |
boolean
|
multiline |
(string ) true , if the value is a multiline text |
Type | Name | Description |
---|---|---|
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
Name | Description |
---|---|
add |
add postings to the timeline |
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 |
Type | Name | Description |
---|---|---|
String
|
token |
the token |
String[]
|
permissions |
The list of permission groups assigned to the token. |
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. |
Type | Name | Description |
---|---|---|
String
|
registeredName |
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 |
Code | Description |
---|---|
200 |
No error. |
201 |
Object created successfully. The object location is provided in Location: header. |
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. |
405 |
Method not allowed. |
409 |
Operation failed. |
500 |
The node configured incorrectly or a bug in the node software; naming service not available. |