API Gateway

The WAMP procedures that load, inspect and remove API Gateway specifications at runtime.

An API specification describes an HTTP API: its paths, and the WAMP action each path performs. Bondy stores each specification under its id in the cluster's replicated storage, and builds HTTP routes from every stored specification. These procedures change the stored set. The same operations are available over HTTP; see API Gateway HTTP API.

AUTHORIZATION

Only a session attached to the master realm (com.leapsight.bondy) can call these procedures. A session in any other realm gets wamp.error.not_authorized.

Procedures

Name	URI
Load an API spec	bondy.http_gateway.api.load
Get an API spec	bondy.http_gateway.api.get
List all API specs	bondy.http_gateway.api.list
Get the status of the API specs	bondy.http_gateway.api.status
Delete an API spec	bondy.http_gateway.api.delete

Bondy also reserves bondy.http_gateway.api.add, but does not implement it. A call to it fails with wamp.error.no_such_procedure. Use bondy.http_gateway.api.load.

Adding and replacing specifications

Load an API spec

bondy.http_gateway.api.load(api_spec)

Validates an API specification, stores it, and rebuilds the HTTP routes so that its paths are served.

Bondy validates the specification by parsing it and compiling its routes. If either step fails, Bondy stores nothing and the routes do not change.

A specification is identified by its id. Loading a specification whose id is already stored replaces the stored one. Bondy stores the specification as submitted.

Loading a specification also creates two groups in the specification's realm, resource_owners and api_clients, if they do not exist. OAuth2 clients and resource owners are users in these groups. The token endpoint checks that a client is in api_clients and a resource owner is in resource_owners.

Call

Positional Args

0object

The api spec data

idstringREQUIREDIMMUTABLE

A global unique identifier for this API.

hoststringREQUIREDIMMUTABLE

A string used for matching the incoming HTTP request HOST header value. Hosts with and without a trailing dot are equivalent for routing. Similarly, hosts with and without a leading dot are also equivalent e.g. cowboy.example.org, cowboy.example.org. and .cowboy.example.org are equivalent. A pattern using the keyword : and wildcard _ can be used to match multiple domains e.g. mydomain.:_ will match mydomain.foo and mydomain.bar but not mydomain.foo.baz. Bondy serves the specification's paths only to requests whose host matches. See Request matching.

realm_uristringREQUIREDIMMUTABLE

The realm this API will target. An API can only target a single realm.

namestringIMMUTABLE

A display name for the API.

metamapIMMUTABLE

A mapping of metadata keys to values.

variablesmapIMMUTABLE

A mapping of arbitrary variable names to values or expressions. This variables can be referenced by expressions in the children objects of this object.

defaultsmapIMMUTABLE

A mapping of attributes to their default values. This values are inherited by children objects as defaults when their value is unset.

status_codesmapIMMUTABLE

A mapping of WAMP Error URIs to HTTP Status Codes. This values are inherited by children objects as defaults when their value is unset.

Default: Check the default values below.

versionsmapREQUIREDIMMUTABLE

A mapping of version names to Version Object instances.

Keyword Args

None.

Result

Positional Results

None.

Keyword Results

None.

Errors

• bondy.error.missing_required_value: the specification omits a required property.
• bondy.error.invalid_value: a property has a value of the wrong type or outside its allowed values.
• bondy.error.http_gateway.invalid_expression: an expression in the specification cannot be parsed.
• bondy.error.internal_error: any other validation failure. This includes an action with no type or an unsupported type, a path that is not valid, the reserved path /ws, and a key the parser does not know at any level of the specification. The node log records the actual reason under "Error while loading API specification".
• wamp.error.invalid_argument: the call does not have exactly one positional argument.
• wamp.error.not_authorized: the session is not attached to the master realm.

Examples

This example loads a partial version of the Marketplace specification. The complete file is api_gateway_config.json.

Request

wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.http_gateway.api.load \
'{
    "id":"com.market.demo",
    "name":"Marketplace Demo API",
    "host":"_",
    "realm_uri":"com.market.demo",
    "meta":{},
    "variables":{},
    "defaults":{
        "retries":0,
        "timeout":15000,
        "connect_timeout":5000,
        "schemes":"{{variables.schemes}}",
        "security":"{{variables.oauth2}}",
        "headers":"{{variables.cors_headers}}"
    },
    "status_codes": {
        "com.example.error.not_found": 404,
        "com.example.error.unknown_error": 500,
        "com.example.error.internal_error": 500
    },
    "versions": {}
}'

Response

The result carries no arguments.

Inspecting specifications

Get an API spec

bondy.http_gateway.api.get(api_spec_id) -> result(api_spec)

Returns the stored specification with the given id, as it was loaded.

Use it to confirm that a specification was stored as you submitted it.

Call

Positional Args

0stringREQUIRED

The id of the API specification.

Keyword Args

None.

Result

Positional Results

0object

The api spec data

idstringREQUIREDIMMUTABLE

A global unique identifier for this API.

hoststringREQUIREDIMMUTABLE

A string used for matching the incoming HTTP request HOST header value. Hosts with and without a trailing dot are equivalent for routing. Similarly, hosts with and without a leading dot are also equivalent e.g. cowboy.example.org, cowboy.example.org. and .cowboy.example.org are equivalent. A pattern using the keyword : and wildcard _ can be used to match multiple domains e.g. mydomain.:_ will match mydomain.foo and mydomain.bar but not mydomain.foo.baz. Bondy serves the specification's paths only to requests whose host matches. See Request matching.

realm_uristringREQUIREDIMMUTABLE

The realm this API will target. An API can only target a single realm.

namestringIMMUTABLE

A display name for the API.

metamapIMMUTABLE

A mapping of metadata keys to values.

variablesmapIMMUTABLE

A mapping of arbitrary variable names to values or expressions. This variables can be referenced by expressions in the children objects of this object.

defaultsmapIMMUTABLE

A mapping of attributes to their default values. This values are inherited by children objects as defaults when their value is unset.

status_codesmapIMMUTABLE

A mapping of WAMP Error URIs to HTTP Status Codes. This values are inherited by children objects as defaults when their value is unset.

Default: Check the default values below.

versionsmapREQUIREDIMMUTABLE

A mapping of version names to Version Object instances.

Keyword Results

None.

Errors

• bondy.error.not_found: no specification with this id is stored.
• wamp.error.invalid_argument: the call does not have exactly one positional argument.
• wamp.error.not_authorized: the session is not attached to the master realm.

Examples

Request

wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.http_gateway.api.get \
'com.market.demo'

Response

{
  "defaults": {
    "connect_timeout": 5000,
    "headers": "{{variables.cors_headers}}",
    "retries": 0,
    "schemes": "{{variables.schemes}}",
    "security": "{{variables.oauth2}}",
    "timeout": 15000
  },
  "host": "_",
  "id": "com.market.demo",
  "meta": {},
  "name": "Marketplace Demo API",
  "realm_uri": "com.market.demo",
  "status_codes": {
    "com.example.error.internal_error": 500,
    "com.example.error.not_found": 404,
    "com.example.error.unknown_error": 500
  },
  "variables": {},
  "versions": {}
}

List all API specs

bondy.http_gateway.api.list() -> result([api_spec])

Returns every stored specification, in the same form as bondy.http_gateway.api.get.

Call

Positional Args

None.

Keyword Args

None.

Result

Positional Results

0array[object]

The list of all loaded api specs.

idstringREQUIREDIMMUTABLE

A global unique identifier for this API.

hoststringREQUIREDIMMUTABLE

A string used for matching the incoming HTTP request HOST header value. Hosts with and without a trailing dot are equivalent for routing. Similarly, hosts with and without a leading dot are also equivalent e.g. cowboy.example.org, cowboy.example.org. and .cowboy.example.org are equivalent. A pattern using the keyword : and wildcard _ can be used to match multiple domains e.g. mydomain.:_ will match mydomain.foo and mydomain.bar but not mydomain.foo.baz. Bondy serves the specification's paths only to requests whose host matches. See Request matching.

realm_uristringREQUIREDIMMUTABLE

The realm this API will target. An API can only target a single realm.

namestringIMMUTABLE

A display name for the API.

metamapIMMUTABLE

A mapping of metadata keys to values.

variablesmapIMMUTABLE

A mapping of arbitrary variable names to values or expressions. This variables can be referenced by expressions in the children objects of this object.

defaultsmapIMMUTABLE

A mapping of attributes to their default values. This values are inherited by children objects as defaults when their value is unset.

status_codesmapIMMUTABLE

A mapping of WAMP Error URIs to HTTP Status Codes. This values are inherited by children objects as defaults when their value is unset.

Default: Check the default values below.

versionsmapREQUIREDIMMUTABLE

A mapping of version names to Version Object instances.

Keyword Results

None.

Errors

• wamp.error.invalid_argument: the call has positional arguments.
• wamp.error.not_authorized: the session is not attached to the master realm.

Examples

Request

wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.http_gateway.api.list

Response

[
  {
    "host": "_",
    "id": "com.market.demo",
    "name": "Marketplace Demo API",
    "realm_uri": "com.market.demo",
    "...": "the remaining properties, as for bondy.http_gateway.api.get"
  }
]

Get the status of the API specs

bondy.http_gateway.api.status() -> result([spec_status])

Returns, for every stored specification, whether the node that answers the call serves it. Each node builds its own HTTP routes, so the answer describes that node only.

Each element is an object with the specification's id and a status:

status	Meaning
active	The specification parsed and its routes are installed.
pending_realm	The specification parsed, but its realm does not exist on this node. The element also carries realm_uri. The next rebuild after the realm appears installs the routes.
rejected	The specification failed to parse and is not served. The element also carries reason, a text description of the failure. The specification stays stored until a call to bondy.http_gateway.api.delete deletes it.
not_built	No route build has run on this node since the specification was stored.

A specification's routes are installed only while its realm exists. Deleting a realm takes down the routes of its specifications. The specifications stay stored as pending_realm. After the realm is created again, the next rebuild on the node installs their routes. Loading or deleting any specification triggers a rebuild.

Call

Positional Args

None.

Keyword Args

None.

Result

Positional Results

An array with one element per stored specification.

Keyword Results

None.

Errors

• wamp.error.invalid_argument: the call has positional arguments.
• wamp.error.not_authorized: the session is not attached to the master realm.

Examples

Request

wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.http_gateway.api.status

Response

[
  {"id": "com.market.demo", "status": "active"}
]

Removing specifications

Delete an API spec

bondy.http_gateway.api.delete(api_spec_id)

Deletes the stored specification with the given id and rebuilds the HTTP routes. The specification's paths stop being served. No listener restart is necessary.

The call succeeds whether or not a specification with this id is stored. The result does not say whether anything was deleted. Call bondy.http_gateway.api.get first if you need to know.

Call

Positional Args

0stringREQUIRED

The id of the API specification to delete.

Keyword Args

None.

Result

Positional Results

One positional result, the string ok.

Keyword Results

None.

Errors

• wamp.error.invalid_argument: the call does not have exactly one positional argument.
• wamp.error.not_authorized: the session is not attached to the master realm.

Examples

Request

wick --url ws://localhost:18080/ws \
--realm com.leapsight.bondy \
call bondy.http_gateway.api.delete \
'com.market.demo'

Response

"ok"