Resource

From Ocean Framework Documentation Wiki
Jump to: navigation, search

The Resource 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/resources

Structure

name
(String) The name of the Resource
description
(String) A plain-text description of the Resource, documenting its use. This is set in the chef-repo in the apps data bag.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "resource": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/resources/7b77cffc-8741-4f5e-ac84-653fa2e5b6fe",
              "type": "application/json"},
            "service": {
              "href": "https://api.example.com/v1/resources/7b77cffc-8741-4f5e-ac84-653fa2e5b6fe/service",
              "type": "application/json"},
            "rights": {
              "href": "https://api.example.com/v1/resources/7b77cffc-8741-4f5e-ac84-653fa2e5b6fe/rights",
              "type": "application/json"}
          },
          "name": "currency",
          "description": "The basic Currencies used in the system.",
          "created_at": "2012-12-01T18:40:53Z",
          "updated_at": "2012-12-03T09:12:17Z",
          "lock_version": 3
  }
}

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

self
as always, the self hyperlink can be used to perform CRUD actions on the Resource resource.
service
retrieves the Service to which this Resource belongs.
rights
GET retrieves the collection of Rights available for this Resource.
POST creates a new Right belonging to this Resource.
documentation
if present, this is a hyperlink to the text/html documentation for the Resource. This can be set in a POST or PUT operation by submitting a string value for the attribute documentation_href.
creator
the ApiUser who created this Resource.
updater
the ApiUser who last updated this Resource.


GET self

Retrieves a Resource resource.

200
The operation was successful.

POST rights

Creates a new Right belonging to this Resource.

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

GET /v1/resources

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

GET /v1/resources?name=text

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

GET /v1/resources?search=dictionary%20entry

Pagination can also be performed using page:

GET /v1/resources?page=3

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

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