Collections and assets

A collection is a self-contained database, that has its own objects, custom fields and taxonomies. This guide covers the basics of retrieving data on your collections and assets.

Collections

For the most part, you won't necessarily need to retrieve a list of collections dynamically, as usually one app would equate to one collection. For example, the PubCrawl app that lists local pubs in the UK is bound to a single collection. That collection can then be subdivided by city or county, but it's all part of the same virtual database.

To retrieve a list of the collections bound to an app, you would make a call like this:

GET /api/manager/collection.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

You'll then get a JSON response like this:

[
   {
      "site":1,
      "id":3,
      "name":"PubCrawl",
      "uid":"tX0k"
   }
]

Subcollections

A collection can be divided up into a number of subcollections. In the PubCrawl example, we have one collection for the app, then a number of sub collections for each city. To request subcollections for a specific collection, note the ID of the collection and pass it in to the following API call:

GET /api/manager/collection/<id>/subcollections.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

A response would look like this:

[
   {
      "children":[],
      "id":11,
      "name":"Belfast",
      "uid":"1KaL"
   },
   {
      "children":[],
      "id":7,
      "name":"Birmingham",
      "uid":"inXB"
   },
   {
      "children":[],
      "id":10,
      "name":"Edinburgh",
      "uid":"GC6q"
   },
   {
      "children":[],
      "id":8,
      "name":"London",
      "uid":"qokA"
   },
   {
      "children":[],
      "id":9,
      "name":"Manchester",
      "uid":"i8u5"
   }
]

Think of subcollections like folders in a file system. Files can exist in the root directory, or in any subdirectory, but not in multiple subdirectories. Subcollections work in the same way. If you wanted a specific asset to be available in different categories, you can use taxonomies.

Remember the cache

This would seem like a good point to raise the issue of caching. API GET requests are cached for five minutes from the first time they're called. This is to reduce the amount of stress that's put on the API, because when your app goes live, it won't just be you making requests! So remember, if you've made a change to some data and it doesn't appear straight away, keep calm and carry on after five minutes. If it's still not giving you an expected response, raise a question in our forum.

Assets

Pubs (as in our PubCrawl example) are represented in the database as assets. To get a list of assets for a specific collection, you'd make a request like this:

GET /api/manager/collection/<collection_id>/assets.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
Accept-Language: en-gb

That will return a response like this:

[
   {
      "status":1,
      "rating":0,
      "resource_types":[
         {
            "count":1,
            "kind":"image",
            "label_plural":"Images",
            "label":"Image"
         },
         {
            "count":1,
            "kind":"feed",
            "label_plural":"Links",
            "label":"Link"
         }
      ],
      "name":"78",
      "links":[
         {
            "url":"http://livebrum.co.uk/venues/78-bar",
            "title":"LiveBrum listing"
         },
         {
            "url":"https://www.facebook.com/78bar",
            "title":"Facebook page"
         }
      ],
      "ordering_name":"78",
      "fields":{},
      "description":"Having had an extensive refurbishment...",
      "curator":1,
      "longitude":"-1.8832707",
      "location":"78",
      "latitude":"52.4757187",
      "comments":0,
      "taxonomies":[],
      "id":2864,
      "uid":"fhcu3rg"
   }
]

Let's look at that in greater detail:

  • The name and ordering_name fields will differ slightly when the name of the asset begins with a word like "a" or "The". In this case, the ordering_name field will omit that opening word, so that you can provide more easily-readable sorted data.
  • The curator field contains the ID of the user who created that particular asset.
  • The latitude and longitude fields contain the coordinates for the asset, and the location field represents the human-readable location. Often this might be a postcode or a full address, as entered when clicking the Set location link for an asset.
  • The id field is the ID of the asset, which you'll use when making more in-depth calls about that particular asset (ie: when returning media or posting ratings and comments).
  • The rating field contains the average rating (assumed to be out of 5) for that asset, while the comments field gives the number of approved comments for that asset.
  • The taxonomies field returns a list of the taxonomies to which the asset is bound. You can find out more about this in the Taxonomies guide.
  • The description field (truncated in this example) gives a full-text description of the asset, in the language requested via the API call (See the [Setting the language] section below for more info).
  • In fields you'll find a JSON object which contains the name of each field, a human-readable label for that field and the data corresponding to the relevant object. See the [Custom fields] guide for more.
  • The links array lists the link resources for the asset. See the [Resources] guide for more.
  • The resource_types object contains a list of the available resources for an asset, so that your app can tell users what's available straight away. Again, see the [Resources] guide for more details.

Only assets marked as Published will be returned in the API, so the status field will always be set to 1 (in the future, this field may be put to more use).

Subcollections and assets

Remember the file system? If you use subcollections, assets that are placed inside subcollections won't appear in the above API call, because you've requested the "root directory". If you want to get the assets inside a particular sub collection, you'll need to make a request like this:

GET /api/manager/collection/<collection_id>/subcollections/<subcollection_id>/assets.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
Accept-Language: en-gb

That will return output exactly like the above example, but picking assets from that particular subcollection, rather than the "root".

Remember, if this isn't the kind of behaviour you want, consider using Taxonomies instead, as that will give you greater flexibility.

Setting the language

Your mobile operating system should give you a language code that you can send via HTTP. For example, British English is represented with the language code en-gb, French as fr and American English as en-us or less accurately, simply en. You can pass that language to the Nymbol API in the Accept-Language HTTP header, as you see in the above example. If it isn't set, the API assumes - rather arrogantly - that content should be delivered in English.

You can distinguish between different forms of the same language (as in the two English examples above). The API will only read the first part of the language code (the two characters before the hyphen) except in the case of Chinese, where zh-cn is used for Chinese simplified text, and zh-tw for Chinese traditinoal. This will probably change and improve in the future, as Nymbol expands its international reach.

Content curators can add a version of an asset description in many different languages, and you can set the language that your user is using via the Accept-Language HTTP header. When you do this, the API automatically returns the text in that language.

Note: Nymbol does not provide translation services. Content curators need to provide their text in any languages they wish it to be made available.

Where text isn't available in a language other than English, the English version will be provided.

Lists vs single objects

The API doesn't make a distinction between a list of data and a call for a single object, in terms of the amount of detail it returns. For example, the amount of detail in the response for collection/1/assets.json would be the same for collection/1/assets/2.json.

Pagination

Because the API responses can contain a fair amount of data, if your collection is large or expected to grow, you might want to consider pagination. You can pass an rpp querystring parameter in your request, to limit the amount of assets that are returned in each call. Then set the page parameter to paginate through each page of results.

Ordering

You can set the order the assets appear by setting the order querystring parameter to the field you'd like to order by. By default this is ordering_name, but you can also order by name, rating or ? (which would randomise the order).

A fun diversion you could try is setting the rpp value to 1 and the order value to ?, thus giving you a random asset from your collection… if that's the sort of thing you're into (no judgement).

Nearby

Pass the latitude and longitude of the user's location to the near querystring (in <lat>,` format) and you'll get the same results, ordered by proximity, with the nearest assets appearing first. As of yet there's no radius, so it doesn't matter how far away the user is from an asset; it'll always show something.

Search

You can allow your users to search for a specific asset, and pass those criteria to the API in the search querystring parameter. The API will search through the content for that collection, and return matching assets.

Currently this search is pretty basic, but will soon incorporate full-text search, such as you might expect from a decent search engine.

Thumbnails

Text lists are all well and good, but things look better with pictures. When you upload images as resources to an asset, the API will automatically pick the first image you upload to use as a thumbnail. You can make a specific image resource as Featured, and the API will use that one instead.

You don't need to make a separate call to get the thumbnail URL for an asset. Just add the thumbsize querystring parameter to your request, specifying the dimensions (in <width>x<height> format). For example:

GET /api/manager/collection/<collection_id>/assets.json?thumbsize=100x100
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7

When you do this, a thumbnail property will be added to each returned object, with a full URL to the image.

Retina displays

You can set the density of the thumbnail to high by adding the thumbdensity querystring parameter. When you do this, the API will return images twice then size as those requested. So in the example above, the API would respond with an image of 200x200 pixels in size.

Multiple thumbnails

In our PubCrawl app example, we'll have a list of pubs with small thumbnails next to each pub. When the user taps a particular pub name, a new screen will show more info about the pub and a larger thumbnail. In order that we don't make the same call twice just for two different thumbnail sizes, we can request multiple sizes, like so:

GET /api/manager/collection/<collection_id>/assets.json?thumbsize=50x50&thumbsize=120x100

A response containing multiple thumbnails will look like this:

[
    {
        "status": 1,
        "name": "78",
        "thumbnail": {
            "50x50": "http:\/\/nymbol.co.uk\/media\/cache\/41\/61\/4161ced42d70e9093e0aa4acf9a976e2.png",
            "150x150": "http:\/\/nymbol.co.uk\/media\/cache\/7b\/62\/7b62c2c44a00b7085ce4c7efe59bc66a.png"
        }
    }
]

A note for XML users

If you prefer to use XML rather than JSON, please note that due to the spec, the API won't respond with XML tags beginning with numbers, so in the case of the above example, the output would look like this:

<results>
    <result>
        <status>1</status>
        <name>78</name>
        <thumbnail>
            <_50x50>http://nymbol.co.uk/media/cache/41/61/4161ced42d70e9093e0aa4acf9a976e2.png</_50x50>
            <_150x150>http://nymbol.co.uk/media/cache/7b/62/7b62c2c44a00b7085ce4c7efe59bc66a.png</_150x150>
        </thumbnail>
    </result>
</results>

The basic difference being that the tag starts with an underscore, not a digit.

Next guide: Resources → ← Previous guide