Right

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The Right 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/rights

Please note that it's not possible to create a new Right by POSTing to the collection URL. As Rights always have a Resource parent, you must instead POST to the rights hyperlink of the Resource for which you want to create the new Right. This pattern is used throughout the API, wherever parented objects are created.

Structure

name
(String) The name of the Right (read only). The name is autogenerated from the name of the service, the name of the resource, the hyperlink, verb, app, and context, all separated by colons. E.g.: media:medium:self:GET:*:*.
description
(String) A plain-text description of the Right, documenting its use.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
hyperlink
(String) The hyperlink (such as self) or * as a wildcard.
verb
(String) The HTTP verb. One of GET, GET*, POST, PUT, DELETE, DELETE*, and * (wildcard). The seemingly non-standard verbs GET* and DELETE* represent collections of resources. (In Rails terms, the GET* refers to the index action, and the DELETE* to an operation which typically would delete all resources.) The verbs form only a convention used for authorisation operations; none of them is used as an actual HTTP method.
app
(String) The application or * as a wildcard.
context
(String) the context or * as a wildcard.

The hyperlink, verb, app and string can all take wildcard values, which means it is possible to create wildcard rights. For instance, a Right where all fields have the value * would match against all authorisation requests for the resource, which means it would grant full access to the resource for those ApiUsers who have such a wildcard Right in their collection of Groups and Roles. It is of course also possible to create Rights with a more restrictive scope (i.e. where not all four attributes have wildcard values), such as for a particular application.

{
 "right": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/rights/6e2879f8-cda7-4a1e-bd1f-a3bce94ef20f",
              "type": "application/json" }
          },
          "name": "auth:rights:self:GET:webshop_client:*",
          "description": "The right to get an individual Right resource in the webshop_client subapplication.",
          "created_at": "2012-12-01T18:40:53Z",
          "updated_at": "2012-12-03T09:12:17Z",
          "lock_version": 2,
          "hyperlink": "self",
          "verb": "GET",
          "app": "webshop_client",
          "context": "*"
  }
}

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

self
as always, the self hyperlink can be used to perform CRUD actions on the Right resource.
resource
the Resource to which this Right belongs.
service
the Service to which the Right belongs via its Resource.
groups
retrieves the collection of Groups that have this Right.
roles
retrieves the collection of Roles that have this Right.
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 Right.
updater
the ApiUser who last updated this Right.


GET self

Retrieves a Right resource.

200
The operation was successful.

PUT self

Updates a Right 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 Right resource.

204
The delete operation was successful.

GET /v1/rights

Returns a collection of Rights. The basic URL returns all Rights 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 Rights whose name property is media:medium:self:GET:*:*:

GET /v1/rights?name=media:medium:self:GET:*:*

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

GET /v1/rights?search=Basket

Pagination can also be performed using page:

GET /v1/rights?page=3

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

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