Resources

A resource is a piece of text, media (image, audio, video) or a link that is associated with an asset. You can have as many resources tied to an asset as you like, and you can include embeddable assets from sites like YouTube and Flickr, and even RSS feeds as resources, by adding them as Links.

Retrieving the resources for an asset

In the Collections and assets guide, we covered how to retrieve a list of assets or a given asset. You can retrieve a list of resources for a specific asset in the following way:

GET /api/manager/collection/<collection_id>/assets/<asset_id>/resources.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

A response might look like this:

[
    {
        "kind":"image",
        "title":"New Street Station",
        "ordering":0,
        "media":"http://nymbol.co.uk/media/collections/l0mf/images/mSVEF6A/cc9ef175-5015-4cce-bfa2-4225af8b3a72",
        "curator":1,
        "approved":true,
        "featured":false,
        "asset":2630,
        "id":3659
    },
    {
        "kind":"video",
        "title":"Birmingham New Street redevelopment",
        "ordering":7,
        "curator":1,
        "approved":true,
        "url_parts":{
            "domain":"www.youtube.com",
            "scheme":"http",
            "params":"",
            "path":"/watch",
            "fragment":"",
            "query":{
                "v":[
                    "pgz0IBvT6iA"
                ]
            }
        },
        "url":"http://www.youtube.com/watch?v=pgz0IBvT6iA",
        "asset":2630,
        "base_kind":"link",
        "id":3783
    },
    {
        "kind":"image",
        "guest":{
            "email_hash":"abc372b5c8f49776adb369847827f8cc",
            "name":"Geoff Guestington"
        },
        "title":"13-03-06",
        "ordering":8,
        "media":"http://nymbol.co.uk/media/collections/l0mf/images/mSVEF6A/9ccf25b1-1d9f-42d5-9c24-068688fd917d.png",
        "curator":1,
        "approved":true,
        "featured":false,
        "asset":2630,
        "id":3968
    }
]

So let's break this down.

  • The kind field represents the type of resource (image, audio, video, link or text).
  • If supplied, the guest field will be an object containing the guest's name and a hash of their email address, which you can use to generate a Gravatar URL (see the User-contributed content guide for more about guest users).
  • The curator field is set to the ID of the user who added the resource. In the case of user-uploaded content, this will be set to the ID of the app's creator, as it's that user account that is bound to the app.
  • The title field contains the title of the resource, but you didn't need me to tell you that.
  • The ordering field contains a number which determines the order the resource should appear (this can be set by the content curator). Don't expect this number to be sequential :)
  • The approved field will be set to true when the resource is cleared to be shown in an app, and featured when this resource should be used as the main visual representation for an asset.
  • The media field contains the full URL of the resource's file (eg: the image URL). In the case of remote resources like YouTube videos, this will be the URL to the page that contains the media (ie: the page on YouTube with the video on it).

Resources are returned in the order specified by the order field.

Remote resourced (like YouTube videos and Flickr images) that are uploaded as links will have a kind property of video or photo, depending on how the Nymbol site determine the content type when the asset is added. They also contain a url_parts object (which you'll see above), which you can use as a handy reference point to decide what your app is able to embed directly, and what the app should link to.

For example, if the domain property of an resource's url_parts object is set to www.youtube.com, you'll know that in iOS you could take the query.v property (which points to the ID of the video) and link the user to youtube:<id>. That would open the user's YouTube app with the video already loaded and ready to play.

A note about third-party resources

We're specific about the fact that, when you add a third-party resource, you're not uploading that resource, but linking to it (hence creating the resource with the Link type, not the Video type). That means that Nymbol doesn't upload or copy the YouTube video or Flickr image, but simply stores a link to it, and a thumbnail if it can find one.

Thumbnails

Video resources (including those from third-party websites) can have thumbnails associated with them. These can be gleaned form the linked media (if Nymbol recognises the site) or set by the content curator. You can retrieve thumbnails for a resource by setting the thumbsize querystring value, as per the instructions in the Collections and assets guide.

Text resources and descriptions

A lesser-used resource type is text. This can be used to provide multiple descriptions of an asset, or extracts of different articles. Text resources behave like any other, except that they don't have any media attached to them.

When resources have descriptions available in a specific language, you'll see that in the description property of the resource's JSON object. See the Setting the language section of the Assets guide for details on how the language is determined from the device making the API request.

Next guide: Taxonomies → ← Previous guide