https://github.com/poetapp/frost-api
Po.et's API Layer
https://github.com/poetapp/frost-api
api frost-api nodejs
Last synced: 11 months ago
JSON representation
Po.et's API Layer
- Host: GitHub
- URL: https://github.com/poetapp/frost-api
- Owner: poetapp
- License: mit
- Created: 2017-10-23T22:48:12.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2020-02-18T01:40:07.000Z (over 6 years ago)
- Last Synced: 2025-08-08T11:16:02.200Z (11 months ago)
- Topics: api, frost-api, nodejs
- Language: TypeScript
- Homepage: https://api.poetnetwork.net
- Size: 1.64 MB
- Stars: 24
- Watchers: 3
- Forks: 5
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Po.et API
[](https://circleci.com/gh/poetapp/frost-api/tree/master)
[](https://renovatebot.com/)
[](https://github.com/semantic-release/semantic-release)
[](https://gitter.im/poetapp/Lobby)
Po.et's API layer for publishers.
- [Getting started](#getting-started)
- [Requirements](#requirements)
- [Install](#install)
- [Development mode](#development-mode)
- [API](#api)
- [Vault](#vault)
- [Consul](#consul)
- [Contributing](#contributing)
- [Coverage](#coverage)
- [Security](#security)
## Getting started
### Requirements
* Node.js (see [`.nvmrc`](./.nvmrc) for the version to install)
* [Docker](https://docs.docker.com/install/) (with [docker-compose](https://docs.docker.com/compose/install/))
## How to Run
To run the Po.et API, clone this repo, and make sure you have [Docker](https://docs.docker.com/install/) and [docker-compose](https://docs.docker.com/compose/install/) installed.
Clone the repo:
```bash
git clone https://github.com/poetapp/frost-api.git
cd frost-api
```
To start the Po.et API development environment, run:
```bash
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
Po.et API depends on [RabbitMQ](http://www.rabbitmq.com/), [IPFS](https://ipfs.io/), [Bitcoin Core](https://github.com/bitcoin/bitcoin), [Po.et node](https://github.com/poetapp/node.git) and [MongoDB](https://github.com/mongodb/mongo).
These dependencies are setup automatically when you run `docker-compose`.
## API
We are using the [OpenAPI specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md) to document the Po.et API:
- https://app.swaggerhub.com/apis-docs/po.et/poet-api/0.1.0#/
### Tokens
There are four types of tokens generated by the Po.et API (see [src/api/Tokens.ts](./src/api/Tokens.ts)). The two main ones used in the Po.et 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
- Forgot Password token - used when resetting a passwordwithout the old password
## Vault
The Po.et API uses [Vault](https://www.vaultproject.io/) to manage API keys.
The API needs Vault to be running, initialized and unsealed.
Currently, if the `VAULT_TOKEN` environment variable isn't set, the API will try and initialize, unseal and configure Vault automatically. This functionality will be removed in future releases.
To manually set up Vault, if using the provided Docker container:
```
sudo docker-compose exec vault vault operator init
sudo docker-compose exec vault vault operator unseal
sudo docker-compose exec vault vault login
```
By default, `init` will create an _Initial Root Token_ and 5 _Unseal Keys_, out of which any three can reconstruct the root token.
The _Root Token_ is what we'll use in the `VAULT_TOKEN` environment variable, and also for the `vault login` command.
The _key shares_ will need to be provided to the `operator unseal` command.
These instructions are perfectly valid for a development environment, for production environments please follow more secure practices.
See also [Vault dev server](https://www.vaultproject.io/intro/getting-started/dev-server.html).
#### Error checking seal status
if you get an `Error checking seal status` error, check the status with:
```bash
curl https://127.0.0.1:8200/v1/sys/seal-status
```
## Consul
See [docs](https://www.consul.io/docs/agent/basics.html).
#### Start
```bash
consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul -bind 127.0.0.1
```
#### Stop
```bash
ps ax | grep consul
kill -INT consul_pid
```
#### Delete data
> WARNING: only use in development mode.
```bash
curl -X DELETE 'http://localhost:8500/v1/kv/vault?recurse'
```
## Contributing
See [Contributing](https://github.com/poetapp/documentation/blob/master/CONTRIBUTING.md).
### Coverage
Coverage is generated with [Istanbul](https://github.com/istanbuljs/nyc). 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](https://github.com/istanbuljs/nyc) and [istanbul-lib-instrument](https://github.com/istanbuljs/istanbuljs/tree/master/packages/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](https://github.com/poetapp/node/pull/230), and check the new PRs for [istanbul-lib-instrument](https://github.com/istanbuljs/istanbuljs/pull/204).
## Security
See https://www.po.et/security.