rest_api_interface

------------------------------------------------------------------------------------------------
| API Resource Model | -------------------------------------------------------------------------
------------------------------------------------------------------------------------------------


   Root url points to latest version of the api eg. https://host:port/v3.0/ same 
as https://host:port/


------------------------------------------------------------------------------------------------
| Obtain an API key | --------------------------------------------------------------------------
------------------------------------------------------------------------------------------------


GET     /admin/<master_api_key>              - returns information about the key.
POST    /admin/<master_api_key>              - returns a new api key
PUT     /admin/<master_api_key>/<api_key_id> - updates the status of the specified key
DELETE  /admin/<master_api_key>/<api_key_id> - invalidates the specified key


------------------------------------------------------------------------------------------------
| Interact with the API | ----------------------------------------------------------------------                                        
------------------------------------------------------------------------------------------------


GET     /                       - retrives metadata about the api eg. version...
GET     /<api_key>              - retrives information about the api key
POST    /                       - create / upload new file - return the resource <token, url> 
                                  POST request requires a valid api key )
PUT     /<token>                - since you cant 'update' a file PUT method relaces the file.
DELETE  /<token>                - delete the resource


------------------------------------------------------------------------------------------------
| Resources | ----------------------------------------------------------------------------------
------------------------------------------------------------------------------------------------

    All resources have a unique url so this could be used as an "id", doing this provides the
ability to link resources, all resources will have a field "href" specifing the absolute url of
a resource.
    All resources that have relations with other resource will have a field specifing the 
absolute url of the resource or collection of resources.

------------------------------------------------------------------------------------------------
| Resources > API Key | ------------------------------------------------------------------------
------------------------------------------------------------------------------------------------
---
GET     /zzz

{
    "_type": "key",
    "_role": "master",
    "href": "https://host:port/admin/zzz",
    "key": "zzz",
    "api_keys": "https://host:port/admin/zzz?expand=keys",
}
---
GET     /zzz?expand=keys

{
    "_type": "key",
    "_role": "master",
    "href": "https://host:port/admin/zzz",
    "key": "zzz",
    "api_keys": [
        "key": {
            "href": "https://host:port/www",
        },
        "key": {
            "href": "https://host:port/abc",
        }
    ],
}
---
GET     /zzz?expand=keys.key

{
    "_type": "key",
    "_role": "master",
    "href": "https://host:port/admin/zzz",
    "key": "zzz",
    "api_keys": [
        "key": {
            "_type": "key",
            "_role": "generic",
            "href": "https://host:port/www",
            "key": "www",
            "tokens": "https://host:port/www",
        },
        "key": {
            "_type": "key",
            "_role": "generic",
            "href": "https://host:port/abc",
            "key": "abc",
            "tokens": "https://host:port/abc",
        }
    ],
}