Contentbox
From n² wiki
This is the Platform API documentation for the Contentbox of a Store. The content box contains a list of content items, e.g. images or other files, that are managed as part of a store.
Contents |
[edit] URI Pattern
http://api.talis.com/stores/{storename}/items
[edit] Resource Operations
| URI Pattern | Method | Request Body | Semantics | Capability required |
|---|---|---|---|---|
| /{storename}/items | GET | Retrieve a query form | basic search | |
| /{storename}/items?query= | GET | Search the Contentbox | basic search | |
| /{storename}/items | POST | Any media type | Store Content in the Contentbox | full update |
[edit] Request Parameters
| Parameter | Required? | Description | Values |
|---|---|---|---|
| query | Yes (for searching) | The query expression used to query the content box | Any valid Text Search Syntax |
| max | No | Specify maximum number of results for a search | A positive integer. Default is 10. There is a fixed maximum of 100 results. |
| offset | No | Specify an offset into search results. Use with max to implement paging. | An integer greater than zero. |
| sort | No | Specify a sort order for the search | A comma separated list of field names that should be used to order the results. Append :d to a field name to sort in descending order. See Sorting Search Results. |
| xsl | No | An XSLT stylesheet to apply to the results. See Transforming Search Results. | The URI of a stylesheet |
| content-type | No | Specify the content type for delivering transformed search results | A mime media type |
[edit] Searching The Contentbox
The Contentbox supports full-text searching over its contents. The basic search capability is required to perform searches. A GET on the Contentbox URI will return an HTML form that can be used to manually search the content box, e.g. to test the searching functionality.
The supported search syntax is documented in Text Search Syntax. The following sections have some notes on sorting and post-processing of results.
A successful search will return an RSS 1.0 document. The service supports transformation of search result to create other formats.
[edit] Sorting Search Results
The sort parameter can be used to specify a sort order for search results. The value of the parameter should be a comma-separated list of field names that should be used for ordering. By default fields are sorted in ascending order. To specify descending ordering, add a :d suffix to the field name.
The names of the fields in a search, including ordering, is specified by the Field Predicate Map for the Store.
[edit] Transforming Search Results
An XSLT stylesheet can be applied to search results in order to generate alternate formats. As the stylesheet may generate any number of different mime types, the content-type parameter can be specified to specify the mime type of the generated document.
Additional URL parameters will be provided to the XSLT stylesheet. Read the docs for the Transformation Service for additional notes on the XSLT functionality.
[edit] Caching Support
Responses from the Contentbox search functionality include HTTP caching headers: Last-Modified and ETag. This allows clients to use an HTTP Conditional Get in order to optimize repeated fetching of search results.
As the search results are delivered as an RSS 1.0 feed, this also means that well-designed feed readers should only re-fetch the feed when it has been changed.
[edit] Storing Content
Content POSTed to the Contentbox URI will be added as a new item. Adding content requires the full update capability.
Generally a successful response will be delivered using a 201 Created HTTP status code with a Location header indicating the URI of the newly created content. Some basic metadata for the resource will also be added to the Metabox, e.g. its content type.
Some content types can be configured for special handling, e.g. to split them into smaller resources or process them to extract additional metadata. This is configured on a per-store basis. If some content is going to be specially handled then a 202 Accepted status code will be returned instead, indicating that the request has been queued for processing by the Platform.
