binder-protocol

A declarative specification of the Binder API that ensures consistency between BinderModules and the client module

Used by 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 object. The endpoints currently defined are (see the API description 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:
3. type string - request parameter type
4. description string - request parameter description
5. required boolean - is this parameter required?
6. description string - description of the endpoint
7. msg string - message that should be displayed when the endpoint request is sent
8. request object - keys for all properties of the HTTP request
9. method string - HTTP method
10. authorized boolean - if the endpoint requires an API token
11. body object - HTTP post body
12. response object - contains a description of the possible response body and error/success handling info
13. body object - response body type description
14. error object - names and handlers for all possible errors that the endpoint can generate (keyed by error name)
15. status number - HTTP response code for the error
16. msg string - description of the error that occurred
17. suggestions [string] - possible fixes for the error
18. 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 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}'
        }
      }
    }
  }