Resource Collections

From Ocean Framework Documentation Wiki
Jump to: navigation, search

Collections of Ocean resources are represented as a special kind of resource by the name of _collection. Collection resources wrap a simple array of resources as an attribute called resources.

This pseudo-resource format allows us to add meta-data to the resource, such as count, total count, page number, total pages, and it also allows us to add a _links structure of hyperlinks, with URIs to itself for CRUD operations, and situational hyperlinks to the first, previous, next and/or last page.

Collection searches are standardised throughout Ocean. This means everywhere a collection can be retrieved, you also have the option to do matching, searching, grouping and paging, in exactly the same manner and using the same syntax regardless of the type of resource.

Minimal Collection Format

{"_collection": { 
  "resources": [... ... ... ...],
  "count": 32
  }
}

Unpaged Collection Format

{"_collection": { 
   "resources": [... ... ... ...],
   "count": 18,
   "total_count": 1324,
   "_links": {"self": 
                {"href": "https://api.example.com/v1/some_collection_uri", 
                 "type": "application/json" }
   }
 }

Paged Collection Format

{"_collection": { 
   "resources": [... ... ... ...],
   "count": 100,
   "total_count": 1324,
   "page_size": 100,
   "page": 10,
   "total_pages": 14,
   "resource_type": "doodad",
   "_links": {"self": 
                {"href": "https://api.example.com/v1/some_collection_uri?page=10&page_size=100", 
                 "type": "application/json" }, 
              "first_page":
                {"href": "https://api.example.com/v1/some_collection_uri?page=0&page_size=100", 
                 "type": "application/json"}, 
              "last_page":
                {"href": "https://api.example.com/v1/some_collection_uri?page=14&page_size=100", 
                 "type": "application/json"}, 
              "previous_page":
                {"href": "https://api.example.com/v1/some_collection_uri?page=9&page_size=100", 
                 "type": "application/json"}, 
              "next_page":
                {"href": "https://api.example.com/v1/some_collection_uri?page=11&page_size=100", 
                 "type": "application/json"}
             }
   }
 }

NB: the first_page, previous_page, next_page, and last_page hyperlinks will only appear when following them is meaningful. This means that they can be used to enable or disable UI buttons, for instance. For instance, the first_page and previous_page link won't appear in a resource describing page 0 where there is no previous page. The other two hyperlinks behave similarly for the other end of the page range.

Collection Searches

Every collection retrieval operation accepts additional parameters to match on resource attributes, to search for substrings, group on attribute values, and perform paging. The documentation for each resource will show what attributes are available for matches and searches, but the general mode of operation is identical throughout Ocean.

We will be using the Text resource as an example.

An HTTP GET to the URI /v1/texts returns a collection of Texts. The basic URL returns all Texts 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 properties:

  • app
  • context
  • name
  • locale
  • created_at

The collection of Text resources will be delivered sorted in updated_at ascending order.

Exact matches

The following returns all Texts whose app property is webshop_client:

GET /v1/texts?app=webshop_client

Similarly, the following returns all Texts matching two properties, in this case all texts in Swedish for the webshop_client app:

GET /v1/texts?app=webshop_client&locale=sv-SE

The above is frequently used to fetch localised UI strings for a web application.

Ranged matches

Matches on the datetime attribute created_at can be ranged. The following will retrieve all Swedish Texts for the application admin_client and the context release_notes created between 1 January 2013 and 1 January 2100:

GET /v1/texts?app=admin_client&context=release_notes&locale=sv-SE&created_at=2013-01-01T00:00:00Z,2100-01-01T00:00:00Z

This, by the way, is the recommended way of obtaining the release notes for a web site application: by supplying different range values depending on the time of the most recently received release note, stored in a cookie, the web client can retrieve such information dynamically and inform the user of new features or bug fixes. The context release_notes is reserved in all app applications for this purpose. Administrators of such release notes can be granted control only of the release_notes context in some or all applications and be granted use of the Admin webtool to manage only release notes. This is easily set up via the Ocean authorisation system of users, roles and groups and their associated rights.

Substring searches

You can also search on substrings in result by using search:

GET /v1/texts?search=London

You can combine this freely with exact matching:

GET /v1/texts?search=London&locale=no-NO

This would retrieve all Norwegian texts mentioning London.

Grouping

You can also group texts on a property (in the SQL sense). The following returns one Text resource for each different app in the database and thus can be used to create menus:

GET /v1/texts?group=app

The group argument can take any of the for values app, context, name, or locale. It can be combined freely with matching. The following would return all names in a context and app:

GET /v1/texts?app=webshop_ipad_app&context=uiElements&group=name

Pagination

Pagination can also be performed using page:

GET /v1/texts?page=3

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

GET /v1/texts?page=0&page_size=100