From Ocean Framework Documentation Wiki
Jump to: navigation, search

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



(String) The name of the Group
(String) A plain-text description of the Group, documenting its use.
if present, this is a hyperlink to the text/html documentation for the Resource. This can be set using a POST or PUT request by submitting a string value for the attribute documentation_href. Groups are created in the chef-repo, in the groups data bag.
(Boolean, read only) If present and true, the Group can't be destroyed.
(String) A datetime string in GMT.
(String) A datetime string in GMT.
 "group": {
          "_links": {
            "self": {
              "href": "",
              "type": "application/json" }
          "name": "Media Manager",
          "description": "This group 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


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 Group resource are:

as always, the self hyperlink can be used to perform CRUD actions on the Group resource.
retrieves the collection of ApiUsers that belong to this Group.
retrieves the collection of Roles this Group consists of.
retrieves the collection of Rights this Group has been assigned directly and not via its Roles.
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).
the ApiUser who created this Group.
the ApiUser who last updated this Group.

GET self

Retrieves a Group resource.

The operation was successful.

PUT self

Updates a Group 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.

The operation was successful.


Deletes a Group resource.

The delete operation was successful.

GET /v1/groups

Returns a collection of Groups. The basic URL returns all Groups 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 Groups whose name property is Odigeo Webmasters:

GET /v1/groups?name=Odigeo%20Webmasters

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

GET /v1/groups?search=Vip

Pagination can also be performed using page:

GET /v1/groups?page=3

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

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

POST /v1/groups

Creates a new Group resource.

The operation was successful and a new Groups 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 Groups resource in the response body.