# binder-protocol

> API description for all Binder servers

Latest version **1.2.0** (published 2016-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install binder-protocol
pnpm add binder-protocol
yarn add binder-protocol
bun add binder-protocol
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2016-07-10 |
| First published | 2016-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Andrew Osheroff |
| Maintainers | andrewosh |
| Keywords | binder, protocol, api, http |

## Links

- npm: https://www.npmjs.com/package/binder-protocol
- Repository: https://github.com/binder-project/binder-protocol
- Issues: https://github.com/binder-project/binder-protocol/issues
- npm.io page: https://npm.io/package/binder-protocol

## Recent versions

- 1.2.0 (latest) — 2016-07-10
- 1.1.2 — 2016-07-10
- 1.1.1 — 2016-07-10
- 1.1.0 — 2016-07-10
- 1.0.4 — 2016-06-20
- 1.0.3 — 2016-05-12
- 1.0.2 — 2016-04-21
- 1.0.1 — 2016-04-21
- 1.0.0 — 2016-03-25

## README

# binder-protocol
A declarative specification of the Binder API that ensures consistency between BinderModules and the client module

Used by [`binder-client`](http://github.com/binder-project/binder-client) to auto-generate the client and CLI interfaces

### install
```
npm install binder-protocol
```

### usage

The protocol declaration is a single JS object, where each bottom-level key represents a Binder API endpoint and the value is a [schema](###schema) object. The endpoints currently defined are (see the [API description](https://github.com/binder-project/binder-docs/blob/master/markdown/api-docs.md) for more detail): 
* build
  * start - start a build
  * status - query the status of a single build
  * statusAll - query the status of all builds
* registry
  * fetch - get a single template
  * fetchAll - get all registered templates
* deploy
  * deploy - launch an instance of a template on the deploy backend
  * status - get the status of a single deployment matching a template/id combo
  * statusAll - get the status of all deployments for a given template

### schema

Each endpoint is defined by the following properties:
 1. `path` string - templated string describing the pathname and any request parameters
 2. `params` object - keys for every request parameter and values describing that parameter's properties:
  1. `type` string - request parameter type
  2. `description` string - request parameter description
  3. `required` boolean - is this parameter required? 
 3. `description` string - description of the endpoint
 4. `msg` string - message that should be displayed when the endpoint request is sent
 5. `request` object - keys for all properties of the HTTP request
  1. `method` string - HTTP method
  2. `authorized` boolean - if the endpoint requires an API token
  3. `body` object - HTTP post body
 6. `response` object - contains a description of the possible response body and error/success handling info
  1. `body` object - response body type description
  2. `error` object - names and handlers for all possible errors that the endpoint can generate (keyed by error name)
   1. `status` number - HTTP response code for the error
   2. `msg` string - description of the error that occurred
   3. `suggestions` [string] - possible fixes for the error
  3. `success` object - handler for the single success outcome that the endpoint can generate

### examples

Here's a simple example from the `deploy` API, but see [`index.js`](index.js) for many more examples.

```
deploy: {
    ...
    
    statusAll: {
      path: '/applications/{template-name}',
      params: {
        'template-name': {
          type: String,
          description: 'name of the template with existing deployments',
          required: false
        }
      },
      description: 'Get information associated with all deployment for a given template',
      msg: 'Getting information about all deployments for {template-name}',
      request: {
        method: 'GET',
        authorized: true
      },
      response: {
        body: [{
          id: String,
          location: String
        }],
        error: {
          badDatabase: {
            status: 500,
            msg: 'Querying the database for all deployments failed',
            suggestions: [
              'ensure that the database is accessible to the deploy server',
              'check the Binder Logstash logs for database-oriented messages'
            ]
          }
        },
        success: {
          status: 200,
          msg: '{results}'
        }
      }
    }
  }
```

---
_Source: https://npm.io/package/binder-protocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._