REST API - nrh/pyrange GitHub Wiki

REST API

All data responses are JSON hashes. HTTP response codes are used to communicate success or failure

4xx responses MAY include additional information in the form of:

{"error":"something something here"}

Query parameters supported by most methods:

  • limit=N - return at most N resources (defaults to 1000)
  • offset=N - skip the first N resources
  • fields=A,B,C - only return the supplied fields. if you request fields that the response would not normally contain, you will see: {"nonexistantfield": null}
  • pretty=N - pretty-print the json, helpful for debugging. defaults to 0 (off)
  • suppress_response_codes=N - always return a 200, even on errors, useful for clients with limited understanding of http response codes. defaults to 0 (off)

Unrecognized query parameters are ignored.

Response codes for GET requests:

  • 200 OK
  • 401 Unauthorized - the resource requires authorization to read, but you haven't authenticated
  • 403 Forbidden - you've authenticated, but have insufficent access to read the resource
  • 404 Not Found

For PUT and DELETE requests, all of the above plus:

  • 201 Created - Successfully created a new resource
  • 400 Bad Request - We couldn't make sense of the body of your PUT.

Access Control

Unless otherwise noted, ACLs are inherited from the namespace containing the resource and any ACLs on more specific resources are additive

Namespaces

/namespaces/

methods supported:

  • GET - gets a list of namespaces
  • PUT - adds new namespaces

/namespaces/nsname

  • GET - get a specific namespace
  • PUT - update the namespace

/namespace/{roles,acls,...}

Get or update specific attributes of the named resource.

> GET /nsblah/roles

< 200 OK
< {"roles":['role1','role2']}

/namespace/roles/role

GET the contents of role

> GET /nsblah/roles/foorole

< 200 OK        /* all attributes are returned */
< {
<   "members":  [],
<   "acls":     [],
<   "tags":     []
< }

PUT: create or update role

> PUT /nsblah/roles/foorole
> {
>   "members":  ['a','b','c'],
>   "acls":     [],
>   "tags":     []
> }
  • In the update case, supply only the attributes you wish to modify

    < 200 OK Updated /nsblah/roles/foorole < 201 OK Created /nsblah/roles/foorole

/namespace/roles/role/members

> GET /nsblah/roles/foorole/members
> PUT /nsblah/roles/foorole/members

/namespace/roles/role/tags

> GET /nsblah/roles/foorole/tags

< 200 OK
< {
<   "tags": ['foo','bar','baz']
< }

< 200 OK
< {
<   "tags": []
< }

> PUT /nsblah/roles/foorole/tags
> {
>   "tags": ['foo','bar','baz']
> }

< 200 OK Updated /nsblah/roles/foorole/tags

/namespace/roles/role/acls

> GET /_namespace_/roles/_role_/acls
< 200 OK
< {
<   "perm": ['read','write'],             /* the client's (computed) permissions to the resource */
<   "acls": ["foo","bar","baz"]
< }

> PUT /_namespace_/roles/_role_/acls      /* sets acls on the role */
> {
>   "acls": ['foo','bar','baz']
> }

< 200 OK Updated /_namespace_/roles/_role_/acls

/namespace/tags

> GET /_namespace_/tags
< 200 OK {"tags":[]}

/namespace/tags/tag

> GET /_namespace_/tags/:tag
< 200 OK {"members":["foo","bar","baz"],"roles":[],"acls":[]}

> GET /_namespace_/tags/:tag/members
< 200 OK {"members":["foo","bar","baz"]}

> GET /_namespace_/tags/:tag/roles
< 200 OK {"roles":["a.b.c"]}

> GET /_namespace_/tags/:tag/acls
< 200 OK {"perm":[],"acls":[]}

> PUT /_namespace_/tags/:tag
> {
>   "roles":  ['foo','bar','baz'],
>   "acls":   ['foo','bar','baz']
> }

< 200 OK Updated /_namespace_/tags/:tag
< 201 OK Created /_namespace_/tags/:tag

/acls

ACLs are not namespaced

> GET /acls/fooacl
< 200 OK { .. }

> PUT /acls/fooacl
> {
>   "read-all":     1, /* true */
>   "write-all":    0, /* false */
>   "read-users":   ['user1','user2'],
>   "write-users":  ['user1','user2'],
>   "read-groups":  ['group1','group2'],
>   "write-groups": ['group1','group2']
> }

< 200 OK Updated /acls/acl
< 201 OK Created /acls/acl

/members

Members are not namespaced. Members cannot be created or updated as normal resources, they can only be created by adding them to roles in a namespace

> GET /members/_member_/roles

< 200 OK
< {
<   "nsfoo": {
<     "roles": ["foo","bar"]
<   }
<   "nsbar": {
<     "roles": ["baz"]
<   }
< }

> GET /members/_member_/tags

< 200 OK {"tags":["foo","bar","baz"]}

> GET /members/_member_/namespaces
< 200 OK {"namespaces":[]}

> GET /members/_member_
< 200 OK {"roles":[],"tags":[],"namespaces":[]}

> GET /members              returns all members
< 200 OK {"members":[]}
< 401 Unauthorized
< 403 Forbidden
< 404 Not Found

/range/

POST /range/ return the range expressions' results