Group

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.)

/v1/groups

Structure

name
(String) The name of the Group
description
(String) A plain-text description of the Group, documenting its use.
documentation
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.
indestructible
(Boolean, read only) If present and true, the Group can't be destroyed.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "group": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/groups/bea38914-5525-44da-944d-75afaa2c94d6",
              "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
  }
}

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

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


GET self

Retrieves a Group resource.

200
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.

200
The operation was successful.

DELETE self

Deletes a Group resource.

204
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
200
The operation was successful. The collection is returned as a JSON array in the response body.

POST /v1/groups

Creates a new Group resource.

201
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.