Text

From Ocean Framework Documentation Wiki
Jump to: navigation, search

Each Text belongs to an Ocean app (the scope of which is entirely up to the client) and to a context within that app. Each Text has a name and a locale (sv-SE, no-NO, en-GB, etc). Collectively these four aspects map to a result string. Thus a Text is a translation from a purely symbolic name to a result in a specific language.

It should be noted that app is a purely arbitrary mnemonic string. It doesn't have to correspond to the name of any Ocean service or client.

The Text 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/texts

Structure

app
(String) The Ocean application in which the Text is used, e.g. "exotic_hotels", "admin_client", etc. This is merely an arbitrary mnemonic string; it doesn't have to correspond to any Ocean server or client application name.
context
(String) The context within an app to which the Text belongs, e.g. "errors", "searchWidget", "motd", etc. The context release_notes is reserved for storage of release notes.
name
(String) The name of this text, used to identify it in a language-independent fashion, e.g. "cancel_button_text", "pageHeader", "EULA", etc.
locale
(String) The locale of the result, in the format xx-YY, where xx is a two-character lowercase ISO language code, and YY is a two-character uppercase ISO country code. The two are separated by a hyphen (not an underscore). E.g.: "en-GB", "en-US", "fr-CA", etc.
mime_type
(String) The MIME type of the result, e.g., "image/jpeg", "image/gif", "text/html; charset=utf-8", etc.
usage
(String) Can be used to store the intended usage of this text, for the purposes of the application. E.g., "link", "translation", "table", etc.
markdown
(Boolean) If true, html will contain the result of converting result from markdown to HTML.
result
(String) The string to use for this name in locale locale. E.g., "Cancel", "Avbryt", etc.
html
(String or Null) Contains the HTML equivalent of result if markdown is true. This field is read-only.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "text": {
          "app": "exotic_hotels",
          "context": "foo",
          "name": "greeting",
          "locale": "sv-SE",
          "mime_type": "text/plain",
          "usage": "text",
          "markdown": false,
          "result": "Hejsan!",
          "html": null,
          "created_at": "2012-12-03T18:40:53Z",
          "updated_at": "2012-12-03T18:40:53Z",
          "lock_version": 0,
           "_links": {
            "self": {
              "href": "https://api.example.com/v1/texts/d4c932a3-4c23-4eac-82a5-a7b8b7c53023",
              "type": "application/json" },
            "creator": {
              "href": "https://api.example.com/v1/api_users/19bda703-6feb-4ab0-95bc-836f4c4d80f2",
              "type": "application/json" },
            "updater": {
              "href": "https://api.example.com/v1/api_users/7e13f6ad-a867-49c8-a8f1-a0a93566e0b1",
              "type": "application/json" }
          }
 }
}

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

self
as always, the self hyperlink can be used to perform CRUD actions on the Text resource.
creator
the ApiUser who created this Text.
updater
the ApiUser who last updated this Text.


GET self

Retrieves a Text resource.

200
The operation was successful.

PUT self

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

204
The delete operation was successful.

GET /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.

Examples

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.

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.

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

GET /v1/texts?search=London

You can combine this freely with property matching:

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

This would retrieve all Norwegian texts mentioning London.

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

POST /v1/texts

Creates a new Text resource.

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