Role

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The Role resource has one public URL. (For information about the difference between Public and Internal URLs and HATEOAS conventions, please see API Structure and Conventions.)

/v1/roles

Structure

name
(String) The name of the Role
description
(String) A plain-text description of the Role, documenting its use.
documentation
if present, this is a hyperlink to the text/html documentation for the Role. This can be set using a POST or a PUT request by submitting a string value for the attribute documentation_href. Core Roles are created in the chef-repo, in the roles data bag.
indestructible
(Boolean, read only) If present and true, the Role can't be destroyed.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "role": {
          "links": {
            "self": {
              "href": "https://api.example.com/v1/roles/b5b9126e-4d8b-418b-91c2-d74835374532",
              "type": "application/json" }
          },
          "name": "Media Manager",
          "description": "This role allows an ApiUser to manipulate Media stored on the Riak nodes.",
          "created_at": "2012-12-01T18:40:53Z",
          "updated_at": "2012-12-03T09:12:17Z",
          "lock_version": 892
  }
}

Hyperlinks

The following hyperlink names are used in the following subsections. To retrieve the URL and Content-Type to use, use the _links hash. Note that the URI may change, and thus you should make no inference on how to construct similar URIs from any previous URI. For more information, refer to Hyperlink URIs are Opaque. You may store hyperlink URIs in permanent storage for later use.

The hyperlinks for a Role resource are:

self
as always, the self hyperlink can be used to perform CRUD actions on the Role resource.
api_users
retrieves the collection of ApiUsers that have this Role.
groups
retrieves the collection of Groups that include this Role.
rights
retrieves the collection of Rights this Role has.
connect
PUT with the query arg href=uri to connect the two resources. The uri is the URL encoded value of the href attribute of the other object's self link. (The body should be empty.)
DELETE with the query arg href=uri to disconnect the two resources. The uri is the URL encoded value of the href attribute of the other object's self link.
When connections are made or broken, ApiUsers affected by the change in effective Rights will have their Authentications deleted and their associated authorisations invalidated. The effect is immediate, which means they will have to reauthorise (transparently or otherwise).
creator
the ApiUser who created this Role.
updater
the ApiUser who last updated this Role.


GET self

Retrieves a Role resource.

200
The operation was successful.

PUT self

Updates a Role resource.

PUT requests, according to the RFC standard, require all resource attributes to be updated simultaneously. However, in Ocean PUT requests have the same semantics as PATCH requests in that it's possible to set individual attributes. The API will reject requests with missing essential attributes. If you receive unknown properties, you must preserve them and pass them back unchanged in PUT and PATCH requests. Other than that, you should ignore them. This enables the API to be upgraded transparently.

200
The operation was successful.

DELETE self

Deletes a Role resource. Also, for all ApiUsers connected to the Role, deletes their Authentications and invalidates all associated authorisations. The effect is immediate.

204
The delete operation was successful.

GET /v1/roles

Returns a collection of Roles. The basic URL returns all Roles in the system. You can add query arguments to the basic URL to perform matches and substring searches, and you can also group on a property.

You can match on the following property:

  • name

The following returns all Roles whose name property is System Administrator:

GET /v1/roles?name=System%20Administrator

You can also search on substrings in description by using search, for instance:

GET /v1/roles?search=Sysadmin

Pagination can also be performed using page:

GET /v1/roles?page=3

The first page is 0. Page size defaults to 25, but can be changed using page_size:

GET /v1/roles?page=0&page_size=100
200
The operation was successful. The collection is returned as a JSON array in the response body.

POST /v1/roles

Creates a new Role resource.

201
The operation was successful and a new Role resource has been created. The response headers will, as is customary, include a standard Location header giving the URI of the newly created resource. To save you the extra request Ocean also returns the new Role resource in the response body.