(Proposed) Native API

APIs

Versioning

After consideration we decided to handle versioning of the API via the URL, we acknowledge that there are other ways of doing so, such as custom headers or via content type negotiation.

One point that helped swing it, is that using content-type negotiation, assumes that resources types will exist indefinately, rather than potentially being removed or repurposed. i.e. it makes the assumption that it is the semantically the same, just with a different presentation of data.

A good read on the subject is Troy Hunts blog post on API Versioning and Stack Overflow.

The API version is seperate to any version of the controller, and is a version of the http contract. The version API is semantically versioned, however only the major version is present in the URL, as a major version increased would be required for a breaking change.

Gateways - /api/v1/gateways

/api/v1/gateways

/api/v1/gateways/<id>/devices

Devices - /api/v1/devices

/api/v1/devices

/api/v1/devices/<id>/capability/<name>/

Zones - /api/v1/zones

/api/v1/zones

/api/v1/zones/<id>

/api/v1/zones/<id>/devices

/api/v1/zones/<id>/capability/<name>/<cmd>

Authentication, Authorization and Accounting

APIs must implement checks against the controllers AAA interface, context, action and resource being acted upon. The principal will be extracted from the context.

Where a user lacks permission to view a resource, 404 should be returned to deny the resource exists, other denials should return 403. In resource lists (where the user is permitted to list resources, but not see them) should simply be excluded from the list.

AAA has two checks which are sematically different, Check is directly due to a users request, i.e. getting a resource by ID, Test is indirect, i.e. the user has requested a list of resources. The difference being that Test is not reported in the accounting records, as it was not the users direct intent.

If APIs contain a list of permitted actions for a user, the Test should be used to test if a user can do so.

Actions and Resources

Gateways

• Gateway:List, resource: * - Permissions to list all gateways.
• Gateway:Show, resource: * | gateway:<id> - Permission to see a gateway.

Devices

• Device:List, resource: * - Permissions to list all devices.
• Device:Show, resource: * | device:<id> | zone:<id> - Permission to see a device and all of its state.

Zones

Device Capability: OnOff

• CapabilityOnOff:On, resource: * | device:<id> | zone:<id> - Permission to turn device on.
• CapabilityOnOff:Off, resource: * | device:<id> | zone:<id> - Permission to turn device off.