Murano vNext API Specification Transition

Few key differences between current version and vNext are extensibility and pluggable architecture. vNext going to have availability to add new services on the fly, without any interference in source code or configuration.

To support features described above we need to slightly change our API specification.

Changes

Several changes are introduced to API specification:

Universal endpoint for services
Tree traversing and set syntax

Major change is universal endpoint for all services. Previously we had endpoints like: “/environment/<env_id>/activeDirectories/*” for each service, and now single endpoint for all services is introduced, like: “/environment/<env_id>/services/*”.

In order to make our API more user-friendly and reduce amount of calls and sent data to API we also introducing two complementing features: tree traversing and set syntax.

Tree traversing gives availability to traverse tree and select specific attribute. Let’s look on some examples in order to study new feature.

We previously had call like: “/environments/<env_id>/activeDirectories/<service_id>” that returns JSON-object with service description:

{
   "id": "96365940588b479294fe8e6dc073db04",
   "name": "acme.dc",
   "created": "2010-11-30T03:23:42Z",
   "updated": "2010-11-30T03:23:44Z",
   "domain": "acme.dc",
   "units": [{
       "id": "d08887df15b94178b244904b506fe85b",
       "isMaster": true,
       "location": "west-dc"
    }, {
       "id": "dcf0de317e7046bea555539f19b8ea84",
       "isMaster": false,
       "location": "west-dc"
   }]
}

All other manipulations with service description is on user, but with new feature user is able to select, for example, domain field with one call: “/environments/<env_id>/services/<service_id>/domain”

Single unit entity could be selected simularly: “/environments/<env_id>/services/<service_id>/units/<unit_id>”

Formal rules:

To select single entity from list user should specify entity id after name of attribute with list as value: <list>/<item_id>. As example units list, from JSON above, could be used.
To select attribute on entity, name of the attribute should be specified: <list>/<item_id>/attribute. Example with selection of domain field demonstrate this rule.

Set syntax combined with tree traversing gives availability to change value of selected attribute with PUT calls. For example, we can set new value for domain field with call: PUT “/environments/<env_id>/services/<service_id>/domain” and sending domain field value as call body.

Adding new items to dictionary is almost same syntax, but we use POST call: POST “/environments/<env_id>/services/<service_id>/units” and sending unit object encoded as JSON as body.

Transition

One of the our goals to introduce new breaking API changes early and one by one to simplify transition to new API version in API stabilization stage. Universal endpoint for services is one of first and major breaking changes that we introducing to our API.

Murano/Blueprints/APIv0.2

Murano vNext API Specification Transition

Changes

Transition