Frost API

Po.et's API layer for publishers

• Getting started
  • Requirements
  • Install
  • Development mode
• API
  • Health check
  • Accounts
  • Works
• Vault
• Consul
• Contributing
  • Coverage
  • Pull requests

Getting started

Requirements

• Node.js (see .nvmrc for the version to install)
• Docker (with docker-compose)
• Frost API token (sign up at frost.po.et to create one)

How to Run Frost API

To run Frost API, clone this repo, and make sure you have Docker and docker-compose installed.

Clone the repo:

git clone https://github.com/poetapp/frost-api.git
cd frost-api

To start the Frost API development environment, run:

docker-compose up --build

You only need to run docker-compose build to create or update the Docker images, and docker-compose up -d to start them. To shut everything down, it is recommended to use docker-compose down --volumes to stop the running containers and clear any data. If you wish to keep data between invocations, use docker-compose down.

You can also docker-compose exec mongo bash to run the mongo shell.

Dependencies

Frost API depends on RabbitMQ, IPFS, Bitcoin Core, Po.et node and MongoDB. These dependencies are setup automatically when you run docker-compose.

API

We are using the OpenAPI specification to document the Frost API:

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/

The purpose of the API is to:

• Facilitate the creation and maintenance of Frost accounts
• Enable Frost account holders to create and view their works on the Po.et Network

Tokens

There are four types of tokens generated by Frost (see src/api/Tokens.ts). The two main ones used in the Frost API methods described below are:

• Login token - used to create and maintain the account
• API token - used for creating and viewing works, for both live (mainnet) and test (testnet) environments

There are two other tokens sent by email:

• Verify Account token - used when verifying an email address (see Verify account below)
• Forgot Password token - used when resetting a password (see Password change token below)

Health check

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/healthCheck

Accounts

Create account

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/createAccount

Returns a Login token.

Verify account

When the user creates a new account the system automatically sends an email for the purpose of verifying the email address. This email contains a link with an embedded token, which the user only needs to click in order to verify the email address. Alternatively, the token can be passed programatically to the server:

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/verifyAccount

Resend verification email

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/resendVerifyEmail

Login to account

Authenticate with email address and password.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/loginAccount

Returns a Login token.

Get account profile

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/getProfile

Password reset

When the user forgets or loses the account password, a new one can be requested programatically.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/passwordReset

An email is sent that contains a link with an embedded token, which the user can click in order to open the Frost website and set a new password.

Password change

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/passwordChange

Password change token

Requires a Forgot Password token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/passwordChangeToken

Tokens

Create token

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/createToken

Returns a "test" or "live" API token.

Get tokens

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/getTokens

Delete token

Requires a Login token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/deleteToken

Works

Create work

Requires an API token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/createWork

Get all works

Requires an API token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/getAllWorks

Get work

Requires an API token.

• https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/default/getWork

Vault

Start

vault server -config=config.hcl

Stop

ps ax | grep vault
kill -INT vault_pid

Get transit keys

curl --header "X-Vault-Token: ..." --request LIST http://localhost:8200/v1/transit/keys

Create s specific key

curl --header "X-Vault-Token: ..." --request POST  http://localhost:8200/v1/transit/keys/my-key

Read a specific key

curl --header "X-Vault-Token: ..." http://localhost:8200/v1/transit/keys/my-key

Error checking seal status

if you get an Error checking seal status error, check the status with:

curl https://127.0.0.1:8200/v1/sys/seal-status

Consul

Start

consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul -bind 127.0.0.1

Stop

ps ax | grep consul
kill -INT consul_pid

Delete data

WARNING: only use in development mode.

curl -X DELETE 'http://localhost:8500/v1/kv/vault?recurse'

Contributing

Coverage

Coverage is generated with Istanbul. A more complete report can be generated by running npm run coverage, which will run npm run coverage:unit and npm run coverage:integration together. You may also execute these commands separately.

Note: We are using our own forks of nyc and istanbul-lib-instrument in order to add better support for TypeScript. We intend to contribute our forks back to nyc and istanbul-lib-instrument in order to make our solution available to the entire community. You can follow the issues in this PR, and check the new PRs for istanbul-lib-instrument.

Security