CIKit Matrix REST API
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.cikit
docroot
.gitignore
.travis.yml
LICENSE
README.md
start.sh

README.md

CIKit Matrix REST API

Build Status Coverage Status

Requirements

  • CIKit
  • Docker

Installation

Do not try to install the package separately! It's a submodule of CIKit.

Local or testing environment

./start.sh
cikit ssh
cd /var/www/cikit-rest-api
# Starts development server.
# Or `NODE_ENV=production npm start &` and `npm stop` to stop the server.
npm start

Stop the container.

cikit env/stop

Start existing container.

cikit env/start

Completely remove the container.

cikit env/rm

Run ESLint.

docker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api && npm run lint'

Run unit and functional tests.

docker exec -i cikit-rest-api.loc bash -c 'cd /var/www/cikit-rest-api && npm test'

Production

Deploy to existing CIKit Matrix.

CIKIT_TAGS="api,ssl" cikit matrix/provision --limit=HOSTNAME --rest-api --ssl-src=/path/to/dir/with/ssl/crts

To deploy to a new Matrix remove the CIKIT_TAGS="api,ssl".

The /path/to/dir/with/ssl/certs must be a valid path to a directory that contains *.crt and *.key SSL certificates. They'll be copied to and used on a server by Nginx (for builds) and by Node.js (REST API server).

Update already deployed API

If CIKit Matrix already uses a REST API and got an update, you'll need to deploy the changes.

CIKIT_TAGS="api" cikit matrix/provision --limit=HOSTNAME --rest-api=deploy

User groups

  • viewer

    Can see the list of droplets.

  • manager

    Can manage (add/delete/start/stop/restart) droplets.

  • owner

    Single per system. Can do everything.

Every role inherits permissions from previous.

CLI

User

Get help.

node ./lib/cli/commands/create-user.js -h

Create an owner of the API (kinda super user that can be only one per system):

node ./lib/cli/commands/create-user.js -u BR0kEN -g owner

Note, that further attempts to create an owner will be declined.

Forcibly invalidate user's authentication token and regenerate a secret key.

node ./lib/cli/commands/create-user.js -u BR0kEN -g owner -r

API

Available endpoints

User

  • POST - /api/v1/user/auth - available for existing users of a system.

    Request an access token:

    curl http://localhost:1337/api/v1/user/auth -X POST -H "Content-Type: application/json" -d '{"username": "BR0kEN", "code": "172459"}'

    Response sample:

    {
      "token_type": "Bearer",
      "expires_in": 7200,
      "access_token": "5e11d712066b99a9868888ec253c1979da9dc8f9823831262139f235ab9d64c3",
      "refresh_token": "3ead5fbb1a4e3953f855d84b304d96b08d10a83cad38ebc544832f2125293f2b"
    }

    Add Authorization: Bearer: ACCESS_TOKEN header or {"access_token": "ACCESS_TOKEN"} to body for every request to an API. If you'll get 401, then the token is expired and you have to send a request for its refreshment (better flow is to store the expires_in in your implementation and check its validity before sending a request to an API).

  • POST - /api/v1/user/auth/refresh - can be accessed by existing user with valid refresh token.

    Refresh an existing access token using the refresh_token given after successful authentication:

    curl http://localhost:1337/api/v1/user/auth/refresh -X POST -H "Content-Type: application/json" -d '{"grant_type": "refresh_token", "refresh_token": "REFRESH_TOKEN"}'

    The structure of a response is the same as for previous API query.

  • DELETE - /api/v1/user/auth/revoke/:user - authorized owner can revoke for anyone, authorized users can revoke for ourselves.

    Revoke access and refresh tokens for a given user (require re-authentication).

    curl http://localhost:1337/api/v1/user/auth/revoke/BR0kEN -X DELETE -H "Content-Type: application/json" -H "Authorization: Bearer REFRESH_TOKEN"

    Response sample:

    {
      "status": "ok"
    }
  • GET - /api/v1/user/auth/setup/:user - authorized owner can request a QR code for setting up an authenticating application.

    curl http://localhost:1337/api/v1/user/auth/setup/BR0kEN -X GET -H "Content-Type: application/json" -H "Authorization: Bearer ACCESS_TOKEN"

    Response sample:

    {
      "qr": "BASE64_ENCODED_PNG",
      "secret": "SECRET_KEY"
    }
  • GET - /api/v1/user/list

  • POST - /api/v1/user/add

  • DELETE - /api/v1/user/delete/:user

The /api/v1/user/add and /api/v1/user/delete returns an updated list of users.

Droplet

  • GET - /api/v1/droplet/list
  • POST - /api/v1/droplet/add
  • PATCH - /api/v1/droplet/stop/:droplet
  • PATCH - /api/v1/droplet/start/:droplet
  • PATCH - /api/v1/droplet/restart/:droplet
  • DELETE - /api/v1/droplet/delete/:droplet

All /api/v1/droplet/* endpoints returns a list of droplets. After add, stop, start, restart and delete an updated list will be returned.