Name: binder-protocol
Owner: Binder
Description: A declarative specification of the Binder API that ensures consistency between BinderModules and the client/CLI
Created: 2016-02-11 22:07:29.0
Updated: 2018-02-03 16:43:43.0
Pushed: 2017-08-18 02:47:39.0
Homepage: null
Size: 19
Language: JavaScript
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
:books: Same functionality. Better performance for you. :books:
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.
Thanks for updating your bookmarked links.
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 binder-protocol
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):
Each endpoint is defined by the following properties:
path
string - templated string describing the pathname and any request parametersparams
object - keys for every request parameter and values describing that parameter's properties:type
string - request parameter typedescription
string - request parameter descriptionrequired
boolean - is this parameter required?description
string - description of the endpointmsg
string - message that should be displayed when the endpoint request is sentrequest
object - keys for all properties of the HTTP requestmethod
string - HTTP methodauthorized
boolean - if the endpoint requires an API tokenbody
object - HTTP post bodyresponse
object - contains a description of the possible response body and error/success handling infobody
object - response body type descriptionerror
object - names and handlers for all possible errors that the endpoint can generate (keyed by error name)status
number - HTTP response code for the errormsg
string - description of the error that occurredsuggestions
[string] - possible fixes for the errorsuccess
object - handler for the single success outcome that the endpoint can generateHere's a simple example from the deploy
API, but see index.js
for many more examples.
oy: {
...
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}'
}
}
}