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 incorrect JSON is provided,
invalid-syntax
error is returned.
-
If value of one of the arguments does not correspond its type,
invalid-argument-value
error is
returned.
-
If authentication is required, but not provided,
authentication.required
error is returned.
-
If invalid authentication token or root secret is provided,
authentication.invalid
error is
returned.
-
If the provided signature is incorrect,
authentication.incorrect-signature
error is returned.
-
If the provided carte is incorrect, one of the following
error codes is returned:
carte.client-address-unknown
- cannot determine client IP address;
carte.unknown-fingerprint
- unknown fingerprint version encoded in the carte;
carte.invalid
- the carte format is invalid;
carte.not-begun
- the timespan of the carte has not begun yet;
carte.expired
- the carte is expired;
carte.unknown-signing-key
- cannot find public key for carte owner;
carte.invalid-signature
- carte signature is invalid.
-
If the request needs a node name, but it is not defined,
node-name-not-set
error is returned.
-
If the request needs a signing key, but it is not defined,
signing-key-not-set
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
;
-
owner - only the owner of the content (posting, comment etc.) may perform this request, use admin
token (for own content on the home node only), carte
(passed in URL parameter
carte
) or signature (if present in the input) for authentication.
-
configurable - access to the request is configurable, the client may refer to the corresponding
access hint to clarify and use token, carte or signature for
authentication.
Standard permission groups are:
admin
- administrator of the node;
owner
- owner of the posting, comment etc.;
public
- anybody.
cid
parameter may be passed with any request. See
Events page for the description of its purpose.
Table of Contents
- Activity Reactions object
- Asyncronous Operations object
- Cartes object
- Comments object
- Comment Revisions object
- Comment Reactions object
- Comment Reaction Totals object
- Credentials object
- Deleted Postings object
- Deleted Posting Revisions object
- Domains object
- Draft Postings object
- Feeds object
- Node Name object
- Notifications object
- People object
- Postings object
- Posting Revisions object
- Posting Draft Revision object
- Posting Reactions object
- Posting Reaction Totals object
- Profile object
- Remote Comments object
- Remote Postings object
- Remote Posting Reactions object
- Settings object
- Stories object
- Subscribers object
- Subscriptions object
- Tokens object
- Web Push object
- Who Am I object
- Structures
Activity Reactions object
Local registry of all activity in the form of reactions performed by the node.
GET /activity/reactions/search
Get the list of all reactions performed by the node, filtered by some criteria.
- Request body:
-
ActivityReactionFilter
- Response:
-
ActivityReactionInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
Asyncronous Operations object
Asyncronous operations pending or just finished on the node.
GET /async-operations/remote-posting-verification/{id}
Get status of the asyncronous operation that performs verification of a remote posting signature.
- Parameters:
-
String id
- asynchronous operation ID
- Response:
-
RemotePostingVerificationInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
async-operation.not-found |
async operation with the given ID is not found |
GET /async-operations/remote-reaction-verification/{id}
Get status of the asyncronous operation that performs verification of the signature of a reaction to a remote posting.
- Parameters:
-
String id
- asynchronous operation ID
- Response:
-
RemoteReactionVerificationInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
async-operation.not-found |
async operation with the given ID is not found |
Cartes object
Cartes - cryptographic tokens used for authentication on any node besides the home node.
GET /cartes
Get a set of cartes that correspond to successive periods of time. The node may decide to return less cartes than the given limit
.
- Parameters:
-
int limit
- maximum number of cartes returned
- Response:
-
CarteSet
- Authentication (read more):
- admin
- Name and signing key:
- required
Comments object
Comments to a posting.
GET /postings/{postingId}/comments
Get a slice of the list of comments, delimited by before
or after
moments (but not both) and the given limit
. If neither before
nor after
are provided, the latest comments are returned. The node may decide to return less comments than the given limit
. The stories are always sorted by moment, ascending.
- Parameters:
-
String postingId
- ID of the posting
-
int before
- filter comments posted at or before this moment
-
int after
- filter comments posted strongly after this moment
-
int limit
- maximum number of comments returned
- Response:
-
CommentsSliceInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
comments.before-after-exclusive |
before and after parameters are not allowed together |
limit.invalid |
limit parameter has an invalid value |
POST /postings/{postingId}/comments
Create a comment from the given text and add it to the given posting. The comment owner must authenticate in some way. If the comment is not signed, it will be kept for a limited period of time and then erased.
- Parameters:
-
String postingId
- ID of the posting
- Request body:
-
CommentText
- Response:
-
CommentCreated
- Authentication (read more):
- owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
GET /postings/{postingId}/comments/{commentId}
Get an individual comment.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
-
String include
- Comma-separated list of additional blocks of information that are needed. The values are:
source
- source text of the comment.
- Response:
-
CommentInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
PUT /postings/{postingId}/comments/{commentId}
Update the comment, creating a new revision of it. The text is processed just like in the POST
request.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Request body:
-
CommentText
- Response:
-
CommentInfo
- Authentication (read more):
- owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
DELETE /postings/{postingId}/comments/{commentId}
Delete the comment. The comment may not be purged from the database immediately, but preserved for some period of time to give a chance to restore it.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Response:
-
CommentTotalInfo
- Authentication (read more):
- admin or owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
Comment Revisions object
All revisions of the comment.
GET /postings/{postingId}/comments/{commentId}/revisions
Get all revisions of the comment.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Response:
-
CommentRevisionInfo[]
- Authentication (read more):
- configurable
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
GET /postings/{postingId}/comments/{commentId}/revisions/{id}
Get an individual revision of the comment.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
-
String id
- ID of the revision
- Response:
-
CommentRevisionInfo
- Authentication (read more):
- configurable
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
comment-revision.not-found |
there is no revision with the given ID |
Comment Reactions object
Reactions ("Likes") - simple textless answers to a comment.
POST /postings/{postingId}/comments/{commentId}/reactions
Add a reaction to the given comment. The reaction owner must authenticate in some way. Only one reaction is allowed from each owner to a particular comment. If a reaction from the same owner to this comment already exists, it is overwritten. If the reaction is not signed, the reaction will be kept for a limited period of time and then erased (the previous reaction of the same owner will be restored, if any).
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Request body:
-
ReactionDescription
- Response:
-
ReactionCreated
- Authentication (read more):
- owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
comment.not-signed |
cannot add a reaction to an unsigned comment |
reaction.not-accepted |
the reaction is not acceptable |
GET /postings/{postingId}/comments/{commentId}/reactions
Get a slice of the list of reactions to the given comment, optionally filtered by reaction type, delimited by before
moment and the given limit
. If before
is not provided, the latest reactions are returned. The node may decide to return less reactions than the given limit
. The reactions are always sorted by moment, descending.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
-
boolean negative
- true
, to filter negative reactions, false
, to filter positive ones
-
int emoji
- filter by reaction code, usually interpreted by clients as emoji code point
-
int before
- filter reactions created at or before this moment
-
int limit
- maximum number of reactions returned
- Response:
-
ReactionsSliceInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
limit.invalid |
limit parameter has an invalid value |
GET /postings/{postingId}/comments/{commentId}/reactions/{ownerName}
Get the detailed information about the reaction of the given owner to the given comment. If no reaction with such owner exist, an empty structure with just commentId
is returned.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
-
String ownerName
- reaction owner node name
- Response:
-
ReactionInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
DELETE /postings/{postingId}/comments/{commentId}/reactions
Delete all reactions to the given comment.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
DELETE /postings/{postingId}/comments/{commentId}/reactions/{ownerName}
Delete the reaction of the given owner to the given comment.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
-
String ownerName
- reaction owner node name
- Response:
-
ReactionTotalsInfo
- Authentication (read more):
- admin or owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
Comment Reaction Totals object
Summary of reactions to a comment.
GET /postings/{postingId}/comments/{commentId}/reaction-totals
Get summary of reactions to the comment given.
- Parameters:
-
String postingId
- ID of the posting
-
String commentId
- ID of the comment
- Response:
-
ReactionTotalsInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
comment.not-found |
there is no comment with the given ID |
comment.wrong-posting |
the comment is not related to the given posting |
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
- Name and signing key:
- not required
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
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
credentials.already-created |
credentials are already created |
PUT /credentials
Update credentials.
- Request body:
-
Credentials
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
DELETE /credentials
Delete credentials.
- Response:
-
Result
- Authentication (read more):
- root secret
- Name and signing key:
- not required
Deleted Postings object
All deleted postings, that are not purged from the database yet.
GET /deleted-postings
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.
- Parameters:
-
int page
- page number, 0 by default
-
int limit
- page size (maximum number of postings returned), the default is defined by the node
- Response:
-
PostingInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
page.invalid |
page parameter has an invalid value |
limit.invalid |
limit parameter has an invalid value |
GET /deleted-postings/{id}
Get an individual deleted posting.
- Parameters:
-
String id
- ID of the posting
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no deleted posting with the given ID |
POST /deleted-postings/{id}/restore
Restore a posting. A new revision is created with the same content as in the latest revision.
- Parameters:
-
String id
- ID of the posting
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
Deleted Posting Revisions object
All revisions of the deleted posting. This object supports the same requests as Posting Revisions object, but uses /deleted-postings
prefix instead of /postings
.
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
- Name and signing key:
- not required
GET /domains/{name}
Get information about the domain with the given hostname. If domain registration for this server is public, this request does not require authentication.
- Parameters:
-
String name
- domain name
- Response:
-
DomainInfo
- Authentication (read more):
- root secret or none
- Name and signing key:
- not required
- 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. If domain registration for this server is public, this request does not require authentication.
- Request body:
-
DomainInfo
- Response:
-
DomainInfo
- Authentication (read more):
- root secret or none
- Name and signing key:
- not required
- 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
- Name and signing key:
- not required
- 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
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
domain.not-found |
there is no domain with the given hostname |
domain.cannot-delete-default |
cannot delete the default domain |
GET /domains/available
Get an available domain name that is recommended for the given node name. The domain name is usually chosen to be close to the node name in English transcription. If domain registration for this server is not public, this request is not accessible.
- Parameters:
-
String nodeName
- node name
- Response:
-
DomainAvailable
- Authentication (read more):
- none
- Name and signing key:
- not required
Draft Postings object
All draft postings.
GET /draft-postings
Get the list of draft postings, page by page. The node may decide to use smaller page size than the given limit
. The postings are always sorted by the creation timestamp, descending.
- Parameters:
-
int page
- page number, 0 by default
-
int limit
- page size (maximum number of postings returned), the default is defined by the node
- Response:
-
PostingInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
page.invalid |
page parameter has an invalid value |
limit.invalid |
limit parameter has an invalid value |
POST /draft-postings
Create a new draft posting from the text given.
- Request body:
-
PostingText
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- required
GET /draft-postings/{id}
Get an individual draft posting.
- Parameters:
-
String id
- ID of the posting
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no draft posting with the given ID |
PUT /draft-postings/{id}
Update the draft posting, overwriting the current revision of it.
- Parameters:
-
String id
- ID of the draft posting
- Request body:
-
PostingText
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- required
- Errors:
-
Code |
Description |
posting.not-found |
there is no draft posting with the given ID |
DELETE /draft-postings/{id}
Delete the draft 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.
- Parameters:
-
String id
- ID of the draft posting
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no draft posting with the given ID |
Feeds object
Feed is a set of stories collected for some purpose. The stories are sorted by moment, descending.
These are the standard feeds that have special meaning:
timeline
- the main feed of publications; instant
- the feed of instant notifications; news
- the main feed of publications gathered from other nodes.
GET /feeds
Get general information about all feeds accessible by client.
- Response:
-
FeedInfo[]
- Authentication (read more):
- none
- Name and signing key:
- not required
GET /feeds/{feedName}
Get general information about the feed.
- Parameters:
-
String feedName
- name of the feed
- Response:
-
FeedInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
feed.not-found |
there is no accessible feed with this name |
GET /feeds/{feedName}/status
Get information about non-read and non-viewed stories in the feed.
- Parameters:
-
String feedName
- name of the feed
- Response:
-
FeedStatus
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
feed.not-found |
there is no accessible feed with this name |
PUT /feeds/{feedName}/status
Update information about non-read and non-viewed stories in the feed.
- Parameters:
-
String feedName
- name of the feed
- Request body:
-
FeedStatusChange
- Response:
-
FeedStatus
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
feed.not-found |
there is no accessible feed with this name |
GET /feeds/{feedName}/stories
Get a slice of the feed, delimited by before
or after
moments (but not both) and the given limit
. If neither before
nor after
are provided, the latest stories are returned. The node may decide to return less stories than the given limit
. The stories are always sorted by moment, descending.
- Parameters:
-
String feedName
- name of the feed
-
int before
- filter stories posted at or before this moment
-
int after
- filter stories posted strongly after this moment
-
int limit
- maximum number of stories returned
- Response:
-
FeedSliceInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
feed.not-found |
there is no accessible feed with this name |
feed.before-after-exclusive |
before and after parameters are not allowed together |
limit.invalid |
limit parameter has an invalid value |
Node Name object
The name of the node. Read more about it in the Overview section. Operations with the node name are performed asynchronously - need to poll the node periodically to get the current status of the operation. Only one operation with the node name may be performed by the node at any moment.
GET /node-name
Get the name of the node. Admin user receives also the current status of the latest operation with the node name.
- Response:
-
NodeNameInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
POST /node-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
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
naming.operation-pending |
another operation with the node name is pending currently |
PUT /node-name
Update the 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
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
naming.operation-pending |
another operation with the node name is pending currently |
registeredNameSecret.empty |
the registered name secret or mnemonic are not provided |
node-name.name-absent |
the node name is not provided and not known by the node |
node-name. |
various errors returned by naming server (see the list)
|
DELETE /node-name
Delete all the information related to the node name (including the signing key) from the node. The name record on the naming server is not touched.
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
naming.operation-pending |
another operation with the node name is pending currently |
Notifications object
Receiver of notifications from other nodes.
POST /notifications
Accept a notification packet from other node. Notification packets older than 10 minutes are ignored. The sending node should update the packet timestamp and the signature and send the packet again. This mechanism prevents attackers from recording and resending old signed packets.
- Request body:
-
NotificationPacket
- Response:
-
Result
- Authentication (read more):
- none
- Name and signing key:
- not required
People object
Information related to other nodes.
GET /people
Get general information about other nodes.
- Response:
-
PeopleGeneralInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
Postings object
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.
POST /postings
Create a new posting from the text given, sign it with the signing key and publish it in the given feeds (if any). The heading and the preview of the posting are created automatically, if needed.
- Request body:
-
PostingText
- Response:
-
PostingInfo
- Authentication (read more):
- configurable
- Name and signing key:
- required
PUT /postings/{id}
Update the posting, creating a new revision of it. The text is processed just like in the POST
request.
- Parameters:
-
String id
- ID of the posting
- Request body:
-
PostingText
- Response:
-
PostingInfo
- Authentication (read more):
- configurable
- Name and signing key:
- required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
posting.not-original |
updating a non-original posting is not allowed |
GET /postings/{id}
Get an individual posting.
- Parameters:
-
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.
- Response:
-
PostingInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
DELETE /postings/{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.
- Parameters:
-
String id
- ID of the posting
- Response:
-
Result
- Authentication (read more):
- configurable
- Name and signing key:
- not required
- 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
- Name and signing key:
- not required
Posting Revisions object
All revisions of the posting.
GET /postings/{postingId}/revisions
Get all revisions of the posting, but not more than limit
. The node may decide to return less revisions than the given limit
.
- Parameters:
-
String postingId
- ID of the posting
-
int limit
- maximum number of revisions returned
- Response:
-
PostingRevisionInfo[]
- Authentication (read more):
- configurable
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
GET /postings/{postingId}/revisions/{id}
Get an individual revision of the posting.
- Parameters:
-
String postingId
- ID of the posting
-
String id
- ID of the revision
- Response:
-
PostingRevisionInfo
- Authentication (read more):
- configurable
- Name and signing key:
- not required
- Errors:
-
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 |
POST /postings/{postingId}/revisions/{id}/restore
Restore a revision of the posting. A new revision is created with the same content as in the given revision.
- Parameters:
-
String postingId
- ID of the posting
-
String id
- ID of the revision
- Response:
-
PostingRevisionInfo
- Authentication (read more):
- owner
- Name and signing key:
- required
- Errors:
-
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 |
Posting Draft Revision object
The draft revisions of the posting - the special revision designed for storing pending changes to the posting that are not published yet.
GET /postings/{postingId}/revisions/draft
Get the posting with the changes stored in its draft revision.
- Parameters:
-
String postingId
- ID of the posting
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
PUT /postings/{postingId}/revisions/draft
Update the draft revision of the posting.
- Parameters:
-
String postingId
- ID of the posting
- Request body:
-
PostingText
- Response:
-
PostingInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
DELETE /postings/{postingId}/revisions/draft
Erase all changes stored in the draft revision of the posting.
- Parameters:
-
String postingId
- ID of the posting
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
Posting Reactions object
Reactions ("Likes") - simple textless answers to a posting.
POST /postings/{postingId}/reactions
Add a reaction to the given posting. The reaction owner must authenticate in some way. Only one reaction is allowed from each owner to a particular posting. If a reaction from the same owner to this posting already exists, it is overwritten. If the reaction is not signed, the reaction will be kept for a limited period of time and then erased (the previous reaction of the same owner will be restored, if any).
- Parameters:
-
String postingId
- ID of the posting
- Request body:
-
ReactionDescription
- Response:
-
ReactionCreated
- Authentication (read more):
- owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
reaction.not-accepted |
the reaction is not acceptable |
GET /postings/{postingId}/reactions
Get a slice of the list of reactions to the given posting, optionally filtered by reaction type, delimited by before
moment and the given limit
. If before
is not provided, the latest reactions are returned. The node may decide to return less reactions than the given limit
. The reactions are always sorted by moment, descending.
- Parameters:
-
String postingId
- ID of the posting
-
boolean negative
- true
, to filter negative reactions, false
, to filter positive ones
-
int emoji
- filter by reaction code, usually interpreted by clients as emoji code point
-
int before
- filter reactions created at or before this moment
-
int limit
- maximum number of reactions returned
- Response:
-
ReactionsSliceInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
limit.invalid |
limit parameter has an invalid value |
GET /postings/{postingId}/reactions/{ownerName}
Get the detailed information about the reaction of the given owner to the given posting. If no reaction with such owner exist, an empty structure with just postingId
is returned.
- Parameters:
-
String postingId
- ID of the posting
-
String ownerName
- reaction owner node name
- Response:
-
ReactionInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
DELETE /postings/{postingId}/reactions
Delete all reactions to the given posting.
- Parameters:
-
String postingId
- ID of the posting
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
DELETE /postings/{postingId}/reactions/{ownerName}
Delete the reaction of the given owner to the given posting.
- Parameters:
-
String postingId
- ID of the posting
-
String ownerName
- reaction owner node name
- Response:
-
ReactionTotalsInfo
- Authentication (read more):
- admin or owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
Posting Reaction Totals object
Summary of reactions to a posting.
GET /postings/{postingId}/reaction-totals
Get summary of reactions to the posting given.
- Parameters:
-
String postingId
- ID of the posting
- Response:
-
ReactionTotalsInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
posting.not-found |
there is no posting with the given ID |
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
- Name and signing key:
- not required
PUT /profile
Update the profile.
- Request body:
-
Profile
- Response:
-
ProfileInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
Remote Comments object
Comments to postings located on other nodes.
POST /nodes/{nodeName}/postings/{postingId}/comments
Add a comment to the posting on the remote node and register it in the registry at the local node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
- Request body:
-
CommentSourceText
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- required
PUT /nodes/{nodeName}/postings/{postingId}/comments/{commentId}
Update a comment to the posting on the remote node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
-
String commentId
- ID of the comment on the remote node
- Request body:
-
CommentSourceText
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- required
DELETE /nodes/{nodeName}/postings/{postingId}/comments/{commentId}
Delete a comment from the registry of all comments at the local node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
-
String commentId
- ID of the comment on the remote node
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
POST /nodes/{nodeName}/postings/{postingId}/comments/{commentId}/verify
Verify the signature of the given comment to the posting on the remote node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
-
String commentId
- ID of the comment on the remote node
- Response:
-
AsyncOperationCreated
- Authentication (read more):
- admin
- Name and signing key:
- not required
Remote Postings object
Postings located on other nodes.
POST /nodes/{nodeName}/postings/{id}/verify
Verify the signature of the given posting.
- Parameters:
-
String nodeName
- name of the remote node
-
String id
- ID of the posting on the remote node
- Response:
-
AsyncOperationCreated
- Authentication (read more):
- admin
- Name and signing key:
- not required
POST /nodes/{nodeName}/postings/{id}/revisions/{revisionId}/verify
Verify the signature of the given revision of a posting.
- Parameters:
-
String nodeName
- name of the remote node
-
String id
- ID of the posting on the remote node
-
String revisionId
- ID of the posting revision
- Response:
-
AsyncOperationCreated
- Authentication (read more):
- admin
- Name and signing key:
- not required
Remote Posting Reactions object
Reactions to postings located on other nodes.
POST /nodes/{nodeName}/postings/{postingId}/reactions
Add a reaction to the posting on the remote node and register it in the registry at the local node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
- Request body:
-
ReactionAttributes
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- required
DELETE /nodes/{nodeName}/postings/{postingId}/reactions
Delete a reaction from the registry of all reactions at the local node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
POST /nodes/{nodeName}/postings/{postingId}/reactions/{ownerName}/verify
Verify the signature of the reaction of the given owner to the posting on the remote node.
- Parameters:
-
String nodeName
- name of the remote node
-
String postingId
- ID of the posting on the remote node
-
String ownerName
- reaction owner node name
- Response:
-
AsyncOperationCreated
- Authentication (read more):
- admin
- Name and signing key:
- not required
Settings object
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 /settings/node
Get all node settings, sorted by name. If a setting has not changed its value from the default, it is omitted.
- Parameters:
-
String prefix
- filter settings whose names start with the given prefix, case-sensitive
- Response:
-
SettingInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
GET /settings/client
Get all client settings, sorted by name.
- Parameters:
-
String prefix
- filter settings whose names start with the given prefix, case-sensitive (client.
prefix must be included)
- Response:
-
SettingInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
GET /settings/node/metadata
Get all node settings metadata, sorted by name.
- Parameters:
-
String prefix
- filter settings whose names start with the given prefix, case-sensitive
- Response:
-
SettingMetaInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
PUT /settings
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.
- Request body:
-
SettingInfo[]
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
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 |
Stories object
All stories. Each story describes something happening in Moera, stories are building blocks for feeds. A story may reference a posting, a remote object etc.
GET /stories/{id}
Get an individual story.
- Parameters:
-
String id
- ID of the story
- Response:
-
StoryInfo
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
story.not-found |
there is no story with the given ID |
PUT /stories/{id}
Update the story.
- Parameters:
-
String id
- ID of the story
- Request body:
-
StoryAttributes
- Response:
-
StoryInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
story.not-found |
there is no story with the given ID |
Subscribers object
All nodes that have subscribed to notifications from this node.
GET /people/subscribers
Get the list of all subscribers, optionally filtered by some criteria.
- Parameters:
-
String nodeName
- filter by subscribed node name, may be omitted
-
String type
- filter by subscription type (see SubscriptionDescription.type
for the list of possible values), may be omitted
- Response:
-
SubscriberInfo[]
- Authentication (read more):
- none
- Name and signing key:
- not required
POST /people/subscribers
Subscribe to a particular group of notifications.
- Request body:
-
SubscriberDescription
- Response:
-
SubscriberInfo
- Authentication (read more):
- owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
subscriber.already-exists |
an identical subscriber already exists |
GET /people/subscribers/{id}
Get an individual subscriber.
- Parameters:
-
String id
- ID of the subscriber
- Response:
-
SubscriberInfo
- Authentication (read more):
- admin or owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
subscriber.not-found |
there is no subscriber with the given ID |
DELETE /people/subscribers/{id}
Delete a subscriber.
- Parameters:
-
String id
- ID of the subscriber
- Response:
-
Result
- Authentication (read more):
- admin or owner
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
subscriber.not-found |
there is no subscriber with the given ID |
Subscriptions object
All nodes that send notifications to this node.
GET /people/subscriptions
Get the list of all subscriptions, optionally filtered by some criteria.
- Parameters:
-
String nodeName
- filter by node name, may be omitted
-
String type
- filter by subscription type (see SubscriptionDescription.type
for the list of possible values), may be omitted
- Response:
-
SubscriptionInfo[]
- Authentication (read more):
- none
- Name and signing key:
- not required
POST /people/subscriptions
Register a subscription to notifications from a particular node.
- Request body:
-
SubscriptionDescription
- Response:
-
SubscriptionInfo
- Authentication (read more):
- admin
- Name and signing key:
- required
- Errors:
-
Code |
Description |
subscription.already-exists |
an identical subscription already exists |
DELETE /people/subscriptions
Delete the subscription described by the given parameters.
- Parameters:
-
String remoteNodeName
- name of the node this node is subscribed to
-
String remoteSubscriberId
- ID of the subscriber on the remote node
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
subscription.not-found |
there is no subscription with the given parameters. |
GET /people/subscriptions/search
Search for subscriptions by the given criteria.
- Request body:
-
SubscriptionFilter
- Response:
-
SubscriptionInfo[]
- Authentication (read more):
- admin
- Name and signing key:
- not required
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
- Name and signing key:
- not required
POST /tokens
Sign in and create a token.
- Request body:
-
Credentials
- Response:
-
TokenCreated
- Authentication (read more):
- none
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
credentials.not-created |
credentials are not created yet |
credentials.login-incorrect |
login or password is incorrect |
Web Push object
Management of Web Push subscriptions.
GET /web-push/key
Get Web Push application key.
- Response:
-
WebPushKey
- Authentication (read more):
- admin
- Name and signing key:
- not required
POST /web-push/subscriptions
Add Web Push subscription.
- Request body:
-
WebPushSubscriptionAttributes
- Response:
-
WebPushSubscriptionInfo
- Authentication (read more):
- admin
- Name and signing key:
- not required
DELETE /web-push/subscriptions/{id}
Delete Web Push subscription.
- Parameters:
-
String id
- ID of the subscription
- Response:
-
Result
- Authentication (read more):
- admin
- Name and signing key:
- not required
- Errors:
-
Code |
Description |
web-push-subscription.not-found |
there is no Web Push subscription with the given ID |
Who Am I object
Brief information about the node.
GET /whoami
Get brief information about the node.
- Response:
-
WhoAmI
- Authentication (read more):
- none
- Name and signing key:
- not required
Structures
AcceptedReactions
Type |
Name |
Description |
String
|
positive |
comma-separated list of codes of the positive reactions that are accepted; a code may be prefixed by 0x to designate hexadecimal number and + to designate a recommended reaction
|
String
|
negative |
comma-separated list of codes of the negative reactions that are accepted (the format is the same as above)
|
ActivityReactionFilter
Type |
Name |
Description |
RemotePosting[]
|
postings |
include only reactions to remote postings from this list |
ActivityReactionInfo
Type |
Name |
Description |
String
|
remoteNodeName |
name of the remote node |
String
|
remotePostingId |
ID of the posting on the remote node |
boolean
|
negative |
true , if the reaction is negative, false , if positive |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
timestamp
|
createdAt |
reaction creation timestamp - the real time when the reaction was created |
AsyncOperationCreated
Type |
Name |
Description |
String
|
id |
ID of the asyncronous operation that was created |
Body
Type |
Name |
Description |
String
|
subject |
plain text |
String
|
text |
HTML |
CarteInfo
Type |
Name |
Description |
String
|
carte |
|
timestamp
|
beginning |
timestamp of the beginning of the carte's life |
timestamp
|
deadline |
timestamp of the end of the carte's life |
CarteSet
Type |
Name |
Description |
String
|
cartesIp |
the client IP address the cartes are bound to |
CarteInfo[]
|
cartes |
the cartes |
Choice
Type |
Name |
Description |
String
|
value |
|
String
|
title |
user-readable title for the value |
ClientReactionInfo
Type |
Name |
Description |
boolean
|
negative |
true , if the reaction is negative, false , if positive |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
timestamp
|
createdAt |
reaction creation timestamp - the real time when the reaction was created |
timestamp
|
deadline |
if present, the reaction will be erased at this time |
CommentCreated
Type |
Name |
Description |
CommentInfo
|
comment |
details of the comment created |
int
|
total |
total number of comments in the posting after the creation |
CommentInfo
Type |
Name |
Description |
String
|
id |
|
String
|
ownerName |
node name of the comment's owner |
String
|
postingId |
ID of the parent posting of the comment |
String
|
postingRevisionId |
ID of the revision of parent posting that was current when the comment was created |
String
|
revisionId |
ID of the current revision of the comment |
int
|
totalRevisions |
total number of revisions the comment has |
String
|
bodyPreview |
preview of the comment's body, a string representation of a JSON structure, may be absent |
String
|
bodySrc |
the source text of the comment, a string representation of a JSON structure, may be absent if not requested
|
byte[]
|
bodySrcHash |
hash of the source text of the comment |
String
|
bodySrcFormat |
format of the source text of the comment, the list of available formats is returned in PostingFeatures
|
String
|
body |
body of the comment, a string representation of a JSON structure |
String
|
bodyFormat |
format of the body of the comment, may have any value meaningful for the client, including:
message - Body structure;
application - an application-specific structure.
|
String
|
heading |
heading of the comment |
RepliedTo
|
repliedTo |
information about the comment this comment is replying to, may be absent |
int
|
moment |
|
timestamp
|
createdAt |
comment creation timestamp - the real time when the comment was created |
timestamp
|
editedAt |
comment editing timestamp - the last time the comment was updated |
timestamp
|
deletedAt |
comment deletion timestamp - the time when the comment was deleted, may be absent |
timestamp
|
revisionCreatedAt |
creation timestamp of the current revision of the comment |
timestamp
|
deadline |
comment purging timestamp - the time when the deleted comment will be purged from the database, may be absent
|
byte[]
|
digest |
cryptographic digest of the comment |
byte[]
|
signature |
the comment's owner signature (use Comment fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
AcceptedReactions
|
acceptedReactions |
types of reactions that the comment accepts |
ClientReactionInfo
|
clientReaction |
details of the existing reaction (if any) of the client's owner |
ReactionTotalsInfo
|
reactions |
reactions summary of the comment |
Operations (read more):
Name |
Description |
edit |
edit the comment |
delete |
delete the comment |
revisions |
view the comment's revisions |
reactions |
view reactions to the comment |
CommentRevisionInfo
Type |
Name |
Description |
String
|
id |
|
String
|
postingRevisionId |
ID of the posting revision that was actual at the moment of creation of this comment revision |
String
|
bodyPreview |
preview of the revision'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, may have any value meaningful for the client, including:
message - Body structure;
application - an application-specific structure.
|
String
|
heading |
heading of the revision |
timestamp
|
createdAt |
revision creation timestamp - the real time when the revision was created |
timestamp
|
deletedAt |
revision deletion timestamp - the time when the revision was deleted, may be absent |
timestamp
|
deadline |
revision deletion timestamp - the time when the revision will be deleted and the previous revision will take its place, may be absent
|
byte[]
|
digest |
cryptographic digest of the revision |
byte[]
|
signature |
the comment's owner signature (use Comment fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
ClientReactionInfo
|
clientReaction |
details of the existing reaction (if any) of the client's owner |
ReactionTotalsInfo
|
reactions |
reactions summary of the revision |
CommentsSliceInfo
Type |
Name |
Description |
int
|
before |
the slice contains all comments before this moment, inclusive. May be the far future. |
int
|
after |
the slice contains all comments after this moment, exclusive. May be the far past. |
CommentInfo[]
|
comments |
the comments |
int
|
total |
total number of comments |
int
|
totalInPast |
number of comments before this slice till the far past |
int
|
totalInFuture |
number of comments after this slice till the far future |
CommentSourceText
Type |
Name |
Description |
String
|
bodySrc |
the source text of the comment, a string representation of a JSON structure |
String
|
bodySrcFormat |
format of the source text of the comment, plain-text by default; the list of available formats is returned in PostingFeatures
|
AcceptedReactions
|
acceptedReactions |
types of reactions that the comment accepts |
String
|
repliedToId |
ID of the comment this comment is replying to |
Validation errors:
Code |
Description |
commentText.bodySrc.blank |
body text is empty |
commentText.bodySrc.wrong-size |
body text is too long |
commentText.bodySrc.wrong-encoding |
body text is formatted incorrectly |
commentText.acceptedReactions.positive.wrong-size |
list of accepted positive reactions is too long |
commentText.acceptedReactions.positive.wrong-pattern |
list of accepted positive reactions has wrong format |
commentText.acceptedReactions.negative.wrong-size |
list of accepted negative reactions is too long |
commentText.acceptedReactions.negative.wrong-pattern |
list of accepted negative reactions has wrong format |
CommentText
Type |
Name |
Description |
String
|
ownerName |
node name of the comment's owner |
String
|
bodyPreview |
preview of the comment's body, a string representation of a JSON structure |
String
|
bodySrc |
the source text of the comment, a string representation of a JSON structure |
String
|
bodySrcFormat |
format of the source text of the comment, plain-text by default; the list of available formats is returned in PostingFeatures
|
String
|
body |
body of the comment, a string representation of a JSON structure |
String
|
bodyFormat |
format of the body of the comment, may have any value meaningful for the client, including:
message - Body structure;
application - an application-specific structure.
|
timestamp
|
createdAt |
comment creation timestamp - the real time when the comment was created |
AcceptedReactions
|
acceptedReactions |
types of reactions that the comment accepts |
String
|
repliedToId |
ID of the comment this comment is replying to |
byte[]
|
signature |
the comment's owner signature (use Comment fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
Validation errors:
Code |
Description |
commentText.bodySrc.blank |
body text is empty |
commentText.bodySrc.wrong-size |
body text is too long |
commentText.bodySrc.wrong-encoding |
body text is formatted incorrectly |
commentText.bodySrcFormat.unknown |
unknown body text format |
commentText.body.blank |
body is empty |
commentText.body.wrong-encoding |
body encoding is incorrect |
commentText.bodyPreview.wrong-encoding |
body preview encoding is incorrect |
commentText.bodyFormat.blank |
body format is not set |
commentText.bodyFormat.wrong-size |
body format is too long |
commentText.createdAt.blank |
body creation timestamp is not set |
commentText.createdAt.out-of-range |
body creation timestamp is too far from the current timestamp |
commentText.acceptedReactions.positive.wrong-size |
list of accepted positive reactions is too long |
commentText.acceptedReactions.positive.wrong-pattern |
list of accepted positive reactions has wrong format |
commentText.acceptedReactions.negative.wrong-size |
list of accepted negative reactions is too long |
commentText.acceptedReactions.negative.wrong-pattern |
list of accepted negative reactions has wrong format |
commentText.repliedToId.not-found |
comment referred in `repliedToId` is not found |
CommentTotalInfo
Type |
Name |
Description |
int
|
total |
total number of comments in the posting after the operation |
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 |
DomainAvailable
Type |
Name |
Description |
String
|
name |
fully-qualified domain name |
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 |
FeedInfo
Type |
Name |
Description |
String
|
feedName |
name of the feed |
String
|
title |
title of the feed |
String
|
subscriberId |
ID of the subscriber, if the client is subscribed to notifications about this feed, null or absent otherwise
|
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
Operations (read more):
Name |
Description |
add |
add stories to the feed |
FeedReference
Type |
Name |
Description |
String
|
feedName |
name of the feed |
timestamp
|
publishedAt |
story publication timestamp - the time the story is published under in the feed |
boolean
|
pinned |
true , if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
|
int
|
moment |
|
String
|
storyId |
ID of the story |
String -> String[]
|
operations |
list of the supported operations (see StoryInfo.operations ) and the corresponding access hints for the story in the feed
|
FeedSliceInfo
Type |
Name |
Description |
int
|
before |
the slice contains all stories before this moment, inclusive. May be the far future. |
int
|
after |
the slice contains all stories after this moment, exclusive. May be the far past. |
StoryInfo[]
|
stories |
the stories |
FeedStatus
Type |
Name |
Description |
int
|
notViewed |
number of stories that have not been viewed yet. |
int
|
notRead |
number of stories that have not been read yet. |
FeedStatusChange
Type |
Name |
Description |
boolean
|
viewed |
new value of the viewed flag (null , if the flag is not changed). |
boolean
|
read |
new value of the read flag (null , if the flag is not changed). |
int
|
before |
change flags for all stories before this moment, inclusive. |
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 |
NotificationPacket
Type |
Name |
Description |
String
|
id |
ID of the notification packet on the sending node (used to filter out duplicates) |
String
|
nodeName |
name of the sending node |
timestamp
|
createdAt |
notification packet creation timestamp |
String
|
type |
notification type |
String
|
notification |
the notification, a string representation of a JSON structure (see Notifications page for details)
|
byte[]
|
signature |
the notification packet sender signature (use NotificationPacket fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
NodeNameInfo
Type |
Name |
Description |
String
|
name |
|
OperationStatus
|
operationStatus |
status of the latest operation with the node name |
timestamp
|
operationStatusUpdated |
the last time the operation status was updated |
String
|
operationErrorCode |
if the operation with the node name was failed, the code of the failure |
String
|
operationErrorMessage |
if the operation with the node 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 node name, prolonging it etc. |
PeopleGeneralInfo
Type |
Name |
Description |
int
|
feedSubscribersTotal |
total number of subscribers of the node |
int
|
feedSubscriptionsTotal |
total number of subscriptions of the node |
PostingFeatures
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:
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 |
String
|
id |
|
String
|
revisionId |
ID of the current revision of the posting |
String
|
receiverRevisionId |
ID of the current revision of the original posting (for cached copies of remote postings only) |
int
|
totalRevisions |
total number of revisions the posting has |
String
|
receiverName |
name of the node where the posting was published (for cached copies of remote postings only) |
String
|
receiverPostingId |
ID of the original posting (for cached copies of remote postings only) |
String
|
ownerName |
node 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:
message - Body structure;
application - an application-specific structure.
|
String
|
heading |
heading of the posting |
timestamp
|
createdAt |
posting creation timestamp - the real time when the posting was created |
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 |
timestamp
|
receiverCreatedAt |
original posting creation timestamp (for cached copies of remote postings only) |
timestamp
|
receiverEditedAt |
original posting editing timestamp (for cached copies of remote postings only) |
timestamp
|
receiverDeletedAt |
original posting deletion timestamp (for cached copies of remote postings only) |
timestamp
|
revisionCreatedAt |
creation timestamp of the current revision of the posting |
timestamp
|
receiverRevisionCreatedAt |
creation timestamp of the current revision of the original posting (for cached copies of remote postings only)
|
timestamp
|
deadline |
posting purging timestamp - the time when the deleted posting will be purged from the database, may be absent
|
boolean
|
draft |
true , if the posting is a draft, false otherwise |
boolean
|
draftPending |
true , if the posting has a pending draft revision, false otherwise, may be absent if not requested
|
byte[]
|
signature |
the posting's owner signature (use Posting fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
FeedReference[]
|
feedReferences |
array of references to the posting from stories in feeds |
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
AcceptedReactions
|
acceptedReactions |
types of reactions that the posting accepts |
ClientReactionInfo
|
clientReaction |
details of the existing reaction (if any) of the client's owner |
ReactionTotalsInfo
|
reactions |
reactions summary of the posting |
boolean
|
reactionsVisible |
true , if the posting allows to view detailed information about reactions to anybody except posting and reaction owners, false otherwise
|
boolean
|
reactionTotalsVisible |
true , if the posting allows to view number of reactions to anybody except the posting owner, false otherwise
|
PostingSourceInfo[]
|
sources |
details of the sources the posting was received from (for cached copies of remote postings only) |
int
|
totalComments |
total number of comments to the posting |
PostingSubscriptionsInfo
|
subscriptions |
existing subscriptions of the client's owner |
Operations (read more):
Name |
Description |
edit |
edit the posting |
delete |
delete the posting |
revisions |
view the posting's revisions |
reactions |
view reactions to the posting |
PostingRevisionInfo
Type |
Name |
Description |
String
|
id |
|
String
|
receiverId |
ID of the original revision (for cached copies of remote postings only) |
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
|
deletedAt |
revision deletion timestamp - the time when the revision was deleted, may be absent |
timestamp
|
receiverCreatedAt |
original revision creation timestamp (for cached copies of remote postings only) |
timestamp
|
receiverDeletedAt |
original revision deletion timestamp (for cached copies of remote postings only) |
byte[]
|
signature |
the revision's owner signature (use Posting fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
ClientReactionInfo
|
clientReaction |
details of the existing reaction (if any) of the client's owner |
ReactionTotalsInfo
|
reactions |
reactions summary of the posting revision |
PostingSourceInfo
Type |
Name |
Description |
String
|
nodeName |
name of the remote node |
String
|
feedName |
name of the feed on the remote node |
String
|
postingId |
ID of the posting on the remote node |
timestamp
|
createdAt |
timestamp when the posting was received from this source |
PostingSubscriptionsInfo
Type |
Name |
Description |
String
|
comments |
ID of the existing subscription to posting comments, if any |
PostingText
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
|
AcceptedReactions
|
acceptedReactions |
types of reactions that the posting accepts |
boolean
|
reactionsVisible |
true , if the posting allows to view detailed information about reactions to anybody except posting and reaction owners, false otherwise
|
boolean
|
reactionTotalsVisible |
true , if the posting allows to view number of reactions to anybody except the posting owner, false otherwise
|
StoryAttributes[]
|
|
list of publications in feeds that must be made after creating the posting (for new postings only) |
Validation errors:
Code |
Description |
postingText.bodySrc.blank |
body text is empty |
postingText.bodySrc.wrong-size |
body text is too long |
postingText.bodySrc.wrong-encoding |
body text is formatted incorrectly |
postingText.bodySrcFormat.unknown |
unknown body text format |
postingText.acceptedReactions.positive.wrong-size |
list of accepted positive reactions is too long |
postingText.acceptedReactions.positive.wrong-pattern |
list of accepted positive reactions has wrong format |
postingText.acceptedReactions.negative.wrong-size |
list of accepted negative reactions is too long |
postingText.acceptedReactions.negative.wrong-pattern |
list of accepted negative reactions has wrong format |
postingText.publications.cannot-modify |
publications field is not allowed in posting modification query |
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 |
ReactionAttributes
Type |
Name |
Description |
boolean
|
negative |
true , if the reaction is negative, false , if positive |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
ReactionCreated
ReactionDescription
Type |
Name |
Description |
String
|
ownerName |
reaction owner node name |
boolean
|
negative |
true , if the reaction is negative, false , if positive |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
byte[]
|
signature |
the reaction owner signature (use Reaction fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
ReactionInfo
Type |
Name |
Description |
String
|
ownerName |
reaction owner node name |
String
|
postingId |
ID of the posting |
String
|
postingRevisionId |
ID of the posting revision, if relevant |
String
|
commentId |
ID of the comment, if relevant |
String
|
commentRevisionId |
ID of the comment revision, if relevant |
boolean
|
negative |
true , if the reaction is negative, false , if positive |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
int
|
moment |
|
timestamp
|
createdAt |
reaction creation timestamp - the real time when the reaction was created |
timestamp
|
deadline |
if present, the reaction will be erased at this time |
byte[]
|
signature |
the reaction owner signature (use Reaction fingerprint)
|
int
|
signatureVersion |
signature version (i.e. fingerprint version) |
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
Operations (read more):
Name |
Description |
delete |
delete the reaction |
ReactionsSliceInfo
Type |
Name |
Description |
int
|
before |
the slice contains all reactions before this moment, inclusive. May be the far future. |
int
|
after |
the slice contains all reactions after this moment, exclusive. May be the far past. |
int
|
total |
total number of reactions in the whole list |
ReactionInfo[]
|
reactions |
the reactions |
ReactionTotalInfo
Type |
Name |
Description |
int
|
emoji |
reaction code, usually interpreted by clients as emoji code point |
int
|
total |
total number of reactions with the given code (may be absent) |
float
|
share |
share the reactions with the given code stand from the total number of reactions (may be absent, if total is present)
|
ReactionTotalsInfo
RegisteredNameSecret
Type |
Name |
Description |
String
|
name |
|
String[]
|
mnemonic |
human-friendly mnemonic of the updating key |
String
|
secret |
base64-encoded secret of the updating key |
RemotePosting
Type |
Name |
Description |
String
|
nodeName |
name of the node |
String
|
postingId |
ID of the posting on the node |
RemotePostingVerificationInfo
Type |
Name |
Description |
String
|
id |
asynchronous operation ID |
String
|
nodeName |
|
String
|
postingId |
|
String
|
revisionId |
|
String
|
status |
status of the operation, may be one of:
-
running - the verification is pending;
-
correct - the signature is correct;
-
incorrect - the signature is incorrect;
-
error - the verification cannot be performed due to an error.
|
String
|
errorCode |
error code |
String
|
errorMessage |
human-readable error message |
RemoteReactionVerificationInfo
Type |
Name |
Description |
String
|
id |
asynchronous operation ID |
String
|
nodeName |
|
String
|
postingId |
|
String
|
reactionOwnerName |
node name of the reaction's owner |
String
|
status |
status of the operation, may be one of:
-
running - the verification is pending;
-
correct - the signature is correct;
-
incorrect - the signature is incorrect;
-
error - the verification cannot be performed due to an error.
|
String
|
errorCode |
error code |
String
|
errorMessage |
human-readable error message |
RepliedTo
Type |
Name |
Description |
String
|
id |
ID of the comment |
String
|
revisionId |
ID of the comment revision |
String
|
name |
node name of the comment's owner |
String
|
heading |
heading of the comment |
byte[]
|
digest |
cryptographic digest of the comment |
Result
Type |
Name |
Description |
String
|
errorCode |
error code |
String
|
message |
human-readable error message |
SettingInfo
Type |
Name |
Description |
String
|
name |
name of the setting |
String
|
value |
value of the setting |
SettingMetaInfo
Type |
Name |
Description |
String
|
name |
name of the setting |
String
|
type |
type of the setting, may be one of:
-
bool - boolean, may have value true or false
-
Duration - period of time, an non-negative integer followed by a single character
designating a measurement unit:
s - seconds;
m - minutes;
h - hours;
d - days.
-
int - integer
-
string - string
|
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
|
SettingTypeModifiers
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 |
StoryAttributes
Type |
Name |
Description |
String
|
feedName |
name of the feed |
timestamp
|
publishAt |
story publication timestamp - the time the story must be published under in the feed |
boolean
|
pinned |
true , if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
|
boolean
|
viewed |
value of the viewed flag (null , if the flag is not changed). |
boolean
|
read |
value of the read flag (null , if the flag is not changed). |
StoryInfo
Type |
Name |
Description |
String
|
id |
|
String
|
feedName |
name of the feed |
String
|
storyType |
type of the story (see Stories page for description of various story types and their meaning)
|
timestamp
|
createdAt |
story creation timestamp - the real time when the story was created |
timestamp
|
publishedAt |
story publication timestamp - the time the story is published under in the feed |
boolean
|
pinned |
true , if the story is pinned (should appear before any non-pinned story in the feed), false otherwise
|
int
|
moment |
|
boolean
|
viewed |
true , if the story has been viewed by node owner, false otherwise |
boolean
|
read |
true , if the story has been read by node owner, false otherwise |
String -> String[]
|
operations |
list of the supported operations (see below) and the corresponding access hints |
String
|
summary |
user-readable summary of the story |
String
|
trackingId |
ID (visible by node admin only) that may be used to update the story viewed/read status without authentication
|
PostingInfo
|
posting |
the posting this story is about (may be absent or contain only ID) |
CommentInfo
|
comment |
the comment this story is about (may be absent or contain only ID) |
String
|
remoteNodeName |
name of the node this story is about (may be absent) |
String
|
remotePostingId |
ID of the posting at remote node this story is about (may be absent) |
String
|
remoteCommentId |
ID of the comment at remote node this story is about (may be absent) |
Operations (read more):
Name |
Description |
edit |
update the story |
delete |
delete the story |
SubscriberDescription
Type |
Name |
Description |
String
|
type |
subscription type, (see SubscriptionDescription.type for the list of possible values)
|
String
|
feedName |
feed name, if the subscription type requires one |
String
|
postingId |
posting ID, if the subscription type requires one |
timestamp
|
lastUpdatedAt |
timestamp of the latest known state of the object, may be absent |
Validation errors:
Code |
Description |
subscriberDescription.type.blank |
type is empty |
subscriberDescription.feedName.blank |
feed name is empty |
subscriberDescription.feedName.not-found |
feed is not found |
subscriberDescription.postingId.blank |
posting ID is empty |
subscriberDescription.postingId.not-found |
posting is not found |
SubscriberInfo
Type |
Name |
Description |
String
|
id |
subscriber ID |
String
|
type |
subscription type, (see SubscriptionDescription.type for the list of possible values)
|
String
|
feedName |
feed name, if the subscription type requires one |
String
|
postingId |
posting ID, if the subscription type requires one |
String
|
nodeName |
name of the subscribed node |
timestamp
|
createdAt |
subscription creation timestamp |
SubscriptionDescription
Type |
Name |
Description |
String
|
type |
subscription type, the possible values are:
feed - subscribe to new stories in the feed;
posting - subscribe to updates to the posting;
posting-comments - subscribe to new comments to the posting.
|
String
|
feedName |
feed name on this node that receives notifications |
String
|
remoteSubscriberId |
ID of the subscriber on the remote node |
String
|
remoteNodeName |
name of the node this node is subscribed to |
String
|
remoteFeedName |
feed name on the remote node, if the subscription type requires one |
String
|
remotePostingId |
posting ID on the remote node, if the subscription type requires one |
String
|
reason |
subscription reason, the well-known values are:
user - node owner asked to subscribe;
mention - node name was mentioned;
comment - node owner commented the posting.
|
Validation errors:
Code |
Description |
subscriptionDescription.type.blank |
type is empty |
subscriptionDescription.feedName.blank |
feed name is empty |
subscriptionDescription.feedName.not-found |
feed is not found |
subscriptionDescription.remoteSubscriberId.blank |
subscriber ID is empty |
subscriptionDescription.remoteSubscriberId.wrong-size |
subscriber ID is too long |
subscriptionDescription.remoteNodeName.blank |
node name is empty |
subscriptionDescription.remoteNodeName.wrong-size |
node name is too long |
subscriptionDescription.remoteFeedName.wrong-size |
remote feed name is too long |
subscriptionDescription.remotePostingId.wrong-size |
posting ID is too long |
subscriptionDescription.reason.blank |
subscription reason is empty |
SubscriptionFilter
SubscriptionInfo
Type |
Name |
Description |
String
|
id |
subscription ID |
String
|
type |
subscription type, (see SubscriptionDescription.type for the list of possible values)
|
String
|
feedName |
feed name on this node that receives notifications |
String
|
remoteSubscriberId |
ID of the subscriber on the remote node |
String
|
remoteNodeName |
name of the node this node is subscribed to |
String
|
remoteFeedName |
feed name on the remote node, if the subscription type requires one |
String
|
remotePostingId |
posting ID on the remote node, if the subscription type requires one |
timestamp
|
createdAt |
subscription creation timestamp |
String
|
reason |
subscription reason (see the list of well-known values in SubscriptionDescription .reason
|
TokenCreated
Type |
Name |
Description |
String
|
token |
the token |
String[]
|
permissions |
The list of permission groups assigned to the token. |
TokenInfo
WebPushKey
Type |
Name |
Description |
String
|
key |
BASE64-encoded key |
WebPushSubscriptionAttributes
Type |
Name |
Description |
String
|
endpoint |
Web Push endpoint URL |
String
|
publicKey |
VAPID public signing key |
String
|
authKey |
VAPID authentication key |
Validation errors:
Code |
Description |
webPushSubscriptionAttributes.endpoint.blank |
endpoint is empty |
webPushSubscriptionAttributes.endpoint.wrong-size |
endpoint is too long |
webPushSubscriptionAttributes.publicKey.blank |
public key is empty |
webPushSubscriptionAttributes.publicKey.wrong-size |
public key is too long |
webPushSubscriptionAttributes.authKey.blank |
auth key is empty |
webPushSubscriptionAttributes.authKey.wrong-size |
auth key is too long |
WebPushSubscriptionInfo
Type |
Name |
Description |
String
|
id |
Web Push subscription ID |
WhoAmI
Type |
Name |
Description |
String
|
nodeName |
|
boolean
|
nodeNameChanging |
true if node name is about to be changed |
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. |
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. |