Medium

From Ocean Framework Documentation Wiki
Jump to: navigation, search

Media are assets for web clients: images, sound files, videos, etc. The API allows all media to be organised according to application and context, just like Texts. Media files are stored on Amazon S3 and are automatically distributed via Amazon CloudFront.

The Medium 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/media

Structure

app
(String) The SOA application in which the Medium is used.
context
(String) The context within an app to which the Medium belongs.
name
(String) The name of this medium, used to identify it in a language-independent fashion.
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. E.g.: "en-GB", "en-US", "fr-CA", etc.
usage
(String) Can be used to store the intended usage of this medium, for the purposes of the application. E.g., "link", "translation", "table", etc.
file_name
(String) The name of the original file.
content_type
(String) The Content-Type of the result, e.g., "image/jpeg", "image/gif", "text/html; charset=utf-8", etc.
bytesize
(Integer) The size in bytes of the medium.
tags
(String) Tags associated with the medium.
delete_at
(String or Null) A datetime when the medium is to autodelete.
email
(String) An email address to notify of the autodelete.
created_at
(String) A datetime string in GMT.
updated_at
(String) A datetime string in GMT.
{
 "medium": {
          "_links": {
            "self": {
              "href": "https://api.example.com/v1/media/43cfe94a-26ef-4206-ad2a-bde250e386ba",
              "type": "application/json" },
            "url" {
              "href": "https://ugh37yogfhbvg3.cloudfront.net/foo/bar/sv-SE/header.jpg",
              "type": "image/jpeg" },
            "creator": {
              "href": "https://api.example.com/v1/api_user/b476c341-a1da-41e7-be7e-48e231ad764f",
              "type": "application/json" },
            "updater": {
              "href": "https://api.example.com/v1/api_user/1880519a-ccef-407d-b0b2-26ea3c4f3bad",
              "type": "application/json" }
          },
          "app": "foo",
          "context": "bar",
          "name": "header-pic",
          "locale": "sv-SE",
          "usage": "",
          "file_name": "header.jpg",
          "content_type": "image/jpeg",
          "bytesize": 10322,
          "tags": "web, layout, header, image",
          "delete_at": "2013-06-01T00:00:00Z",
          "email": nil,
          "created_at": "2012-12-03T18:40:53Z",
          "updated_at": "2012-12-03T18:40:53Z",
          "lock_version": 0
  }
}

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.

self
as always, the self hyperlink can be used to perform CRUD actions on the Medium resource.
url
The CloudFront URL and Content-Type for the medium.
creator
The ApiUser who created this medium.
updater
The ApiUser who last updated this medium.


GET self

Retrieves a Medium resource.

200
The operation was successful.

PUT self

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

204
The delete operation was successful.

GET /v1/media

Returns a collection of Medium resources. The basic URL returns all Medium 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 and group on the following properties:

  • app
  • context
  • name
  • locale
  • content_type

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

Examples

The following returns all media whose app property is webshop_client:

GET /v1/media?app=webshop_client

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

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

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

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

GET /v1/media?search=jpg

You can also group media on a property (in the SQL sense). The following returns one Medium resource for each different content_type in the database::

GET /v1/media?group=content_type

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

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

Pagination can also be performed using page:

GET /v1/media?page=3

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

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

POST /v1/media

Creates a new Medium resource. Required parameters:

  • app
  • context
  • locale
  • name
  • content_type
  • file_name

Optional parameters:

  • payload — If given, it should be the base 64-encoded binary data for the resource, which will be uploaded to S3 and made available through CloudFront. If not given, it is assumed that the data already is in place in the S3 bucket.
  • bytesize
  • tags
  • delete_at
  • email
201
The operation was successful and a new Medium 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 Medium resource in the response body.