binder-project / binder-protocol

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

💨 💨 The Binder Project is moving to a new repo. 💨 💨

📚 Same functionality. Better performance for you. 📚

Over the past few months, we've been improving Binder's architecture and infrastructure. We're retiring this repo as it will no longer be actively developed. Future development will occur under the JupyterHub organization.

• All development of the Binder technology will occur in the binderhub repo
• Documentation for users will occur in the jupyterhub binder repo
• All conversations and chat for users will occur in the jupyterhub binder gitter channel

Thanks for updating your bookmarked links.

💨 💨 The Binder Project is moving to a new repo. 💨 💨

---

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}'
        }
      }
    }
  }