Admin HTTP API

The Admin HTTP API exposes Bondy's administration procedures over HTTP. Each route calls one procedure of the WAMP Admin API, and that procedure's reference page is the contract for its arguments, results and errors. This page lists the routes and how an HTTP request maps onto the procedure call.

The routes are served by the admin_api service. Bondy's default admin listener carries it on port 18081, bound to loopback. See Network Listeners.

Protect the listener, not the route

The Admin HTTP API declares no authentication scheme. Anyone who can reach a listener carrying the admin_api service can administer every realm. Keep that listener on loopback or a private network, and never mount admin_api on a listener that serves the public.

Request and response mapping

Every route follows the same rules:

• Base path. Routes are served at the paths below, and also under the prefix /v1.0.
• Positional arguments. Path parameters become the procedure's positional arguments, in the order they appear in the path. For routes that send a body, the JSON request body is the next positional argument.
• Result. A successful call answers with the procedure's first positional result as the JSON response body.
• Errors. A failed call answers with the error's keyword arguments as the JSON body, with code replaced by the error URI. The HTTP status is the error's status from the Error Reference. For example, bondy.error.not_found maps to 404 and bondy.error.already_exists to 400. An error URI that the catalogue does not hold answers 500.
• OPTIONS. Every path also answers OPTIONS, with an empty body.

Routes

Realms

Method	Path	WAMP procedure
GET	/realms	bondy.realm.list
POST	/realms	bondy.realm.create
GET	/realms/:realm_uri	bondy.realm.get
PUT	/realms/:realm_uri	bondy.realm.update
DELETE	/realms/:realm_uri	bondy.realm.delete
GET	/realms/:realm_uri/security_enabled	bondy.realm.security.is_enabled
PUT	/realms/:realm_uri/security_enabled	bondy.realm.security.enable
DELETE	/realms/:realm_uri/security_enabled	bondy.realm.security.disable

Users

Method	Path	WAMP procedure
GET	/realms/:realm_uri/users	bondy.user.list
POST	/realms/:realm_uri/users	bondy.user.add
GET	/realms/:realm_uri/users/:id	bondy.user.get
PUT	/realms/:realm_uri/users/:id	bondy.user.update
DELETE	/realms/:realm_uri/users/:id	bondy.user.delete
POST	/realms/:realm_uri/users/:id/change_password	bondy.user.change_password
GET	/realms/:realm_uri/users/:id/enabled	bondy.user.is_enabled
PUT	/realms/:realm_uri/users/:id/enabled	bondy.user.enable
DELETE	/realms/:realm_uri/users/:id/enabled	bondy.user.disable
POST	/realms/:realm_uri/users/:id/aliases	bondy.user.add_alias
PUT	/realms/:realm_uri/users/:id/aliases/:alias	bondy.user.add_alias
DELETE	/realms/:realm_uri/users/:id/aliases/:alias	bondy.user.remove_alias
PUT	/realms/:realm_uri/users/:id/groups/:group	bondy.user.add_group
DELETE	/realms/:realm_uri/users/:id/groups/:group	bondy.user.remove_group
POST	/realms/:realm_uri/services/change_password	bondy.user.change_password

Groups

Method	Path	WAMP procedure
GET	/realms/:realm_uri/groups	bondy.group.list
POST	/realms/:realm_uri/groups	bondy.group.add
GET	/realms/:realm_uri/groups/:id	bondy.group.get
PUT	/realms/:realm_uri/groups/:id	bondy.group.update
DELETE	/realms/:realm_uri/groups/:id	bondy.group.delete

OAuth2 clients and resource owners

Method	Path	WAMP procedure
POST	/realms/:realm_uri/clients	bondy.oauth2.client.add
PUT	/realms/:realm_uri/clients/:id	bondy.oauth2.client.update
DELETE	/realms/:realm_uri/clients/:id	bondy.oauth2.client.delete
POST	/realms/:realm_uri/resource_owners	bondy.oauth2.resource_owner.add
PUT	/realms/:realm_uri/resource_owners/:id	bondy.oauth2.resource_owner.update
DELETE	/realms/:realm_uri/resource_owners/:id	bondy.oauth2.resource_owner.delete

Grants and sources

Method	Path	WAMP procedure
GET	/realms/:realm_uri/grants	bondy.realm.grants
POST	/realms/:realm_uri/grants	bondy.grant.create
PUT	/realms/:realm_uri/grants	bondy.grant.revoke
GET	/realms/:realm_uri/groups/:id/grants	bondy.group.grants
GET	/realms/:realm_uri/users/:id/grants	bondy.user.grants
GET	/realms/:realm_uri/sources	bondy.source.list
POST	/realms/:realm_uri/sources	bondy.source.add
GET	/realms/:realm_uri/users/:id/sources	bondy.source.match
DELETE	/realms/:realm_uri/users/:id/sources	bondy.source.delete

Registrations and subscriptions

Method	Path	WAMP procedure
GET	/realms/:realm_uri/callees	bondy.wamp.callee.list — broken: no procedure has this name, so the route answers with an error
GET	/realms/:realm_uri/callees/:session_id	bondy.wamp.callee.get — broken: no procedure has this name, so the route answers with an error
GET	/realms/:realm_uri/registrations	bondy.registration.list
GET	/realms/:realm_uri/registrations/:id	bondy.registration.get
GET	/realms/:realm_uri/registrations/:id/callees	bondy.registration.list_callees
GET	/realms/:realm_uri/subscriptions	bondy.subscription.list

The /registrations and /subscriptions routes answer with the first page of the paginated procedure. The body holds values, has_more and, when more entries remain, cursor. Each entry carries its id and its match policy. These routes pass no limit or cursor to the procedure, so the page has the default size and no route reads the next page. Use POST /services/call to call the procedure with limit and cursor.

API Gateway specifications

Method	Path	WAMP procedure
POST	/services/load_api_spec	bondy.http_gateway.api.load
GET	/api_specs	bondy.http_gateway.api.list
POST	/api_specs	bondy.http_gateway.api.load
GET	/api_specs/:id	bondy.http_gateway.api.get
DELETE	/api_specs/:id	bondy.http_gateway.api.delete
GET	/api_specs/:id/info	bondy.http_gateway.api.get

Backup and restore

Method	Path	WAMP procedure
POST	/services/create_backup	bondy.export.create
GET	/services/backup_status	bondy.export.status
POST	/services/restore_backup	bondy.export.import

Calling any procedure

Method	Path	WAMP procedure
POST	/services/call	The procedure named in the body

POST /services/call takes a body of the form {"procedure": ..., "args": [...], "kwargs": {...}, "options": {...}}, calls that procedure, and answers with {"args": ..., "kwargs": ..., "details": ...}.