Node API

Moera Node API is a JSON-based REST API. See introduction to Node REST API in the Architecture Overview section. Until the API is stabilized, it may be changed in various ways and backward compatibility is not guaranteed.

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

Table of Contents

1. Requests
2. Events
3. Notifications
4. Virtual Pages
5. Headers
6. Node Name
7. Moment
8. Authentication
9. Access Controls
10. Fingerprints

General errors

If an error occurs when processing an 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 the request Content-Type is unknown, invalid-content-type error is returned.
• If incorrect JSON is provided, invalid-syntax error is returned.
• If the request is correct, but the operation is not supported by the node, not-supported 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 an 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 the carte owner;
  • carte.invalid-signature – carte signature is invalid.
• If the node is blocked from performing the operation, authentication.blocked error is returned.
• 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 requirements

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

• none or not present – authentication is not needed, it does not affect the request;
• optional – authentication is not mandatory, but it does affect the request;
• required – authentication is required to perform the request;
• signature – signature should be included in the request body;
• root admin – the client should authenticate as server administrator to perform the request;
• admin – the client should authenticate as node administrator to perform the request.

CID

cid parameter may be passed with any request. See Events page for the description of its purpose.