User-contributed content

As well as retrieving content from the Nymbol database, you can also let your users talk back, by posting comments on assets and rating them, and uploading photos and videos. Most of this stuff uses the Guest model, so let's look at that first.

Guests

A guest is a virtual user account, tied to an email address. When posting a comment or uploading a resource like a photo, it's necessary to supply information about the user who is posting that content. You don't need to worry about maintaining IDs or usernames; Nymbol handles that, and ties guest accounts to devices for analytics.

If you don't supply guest details when required, you'll receive an HTTP response with an error object, which details the missing or invalid data.

When POSTing to the API, include the following details when adding comments or uploading resources:

  • guest_name: a free-text field, which should be the user's full name, as you'd expect to see it on any blog's comments form
  • guest_email: a valid email address which the system doesn't share or reveal to outside users, but which is available to content curators

You should also include the following HTTP headers, so that the guest's device can be tied to their virtual account (this doesn't affect the end user but is better for analytics):

  • X-Platform: set to iphone, ipad, android, winphone, blackberry, html5 or other
  • X-Device: the universal ID of the device. You don't need to enable push notifications or any such service for this, but you may want to consider your privacy policy

These two headers are optional for posting comments and uploading resources, but is required for ratings, as it's the only distinguishing data that allows the system to cancel out repeat ratings from the same user.

A note about the X-Device header

The X-Device header doesn't identify the specific device in a way that can be usable (ie: push notifications will usually require a different token because the operating system wants to ensure explicit consent from the user), but simply distinguishes one device from another. If you're concerned about the privacy of this data, feel free to hash or encrypt the value so that it's obfuscated. It doesn't have to conform to any spec, but should simply distinguish the device from others using the system. The device ID is not not revealed to content curators, nor is it made available in the API.

Posting comments

Comments can be posted to an asset in a collection or subcollection. To submit a user's comment, you need to perform an HTTP POST like this:

POST /api/manager/collection/<collection_id>/assets/<asset_id>/comments.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
X-Platform: iphone
X-Device: 9de7219d-c8cf-45d1-b8ab-c6a440071f3f
enctype: application/x-www-form-urlencoded

guest_name=Geoff+Guestington
&guest_email=geoff@guestington.com
&body=Body+of+the+comment

Those last three lines are the body of the POST. Your library should abstract this to a degree, perhaps making it possible to pass a dictionary or array of data to a function that encodes it and adds it to the request. The fields you need to submit are:

  • guest_name: the name of the user submitting the comment
  • guest_email: the email address of the commenter
  • body: The body text of the comment

Once POSTed, the comment will be queued for validation by the content curators, who will receive a notification that a new comment is ready for review.

That's it. Pretty simple, really.

Posting ratings

You can let your users rate assets by submitting the following request:

POST /api/manager/collection/<collection_id>/assets/<asset_id>/ratings.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
X-Platform: iphone
X-Device: 9de7219d-c8cf-45d1-b8ab-c6a440071f3f
enctype: application/x-www-form-urlencoded

rate=4

The rate value should be a number (ie: "how many stars, out of 5 would you give it?"). You can choose the maximum number yourself, but 5 is probably the best.

If the user has already rated an asset, the API will overwrite their rating and replace it with the new one. That's why it's essential to submit your request with the X-Device header, otherwise the API will throw an error.

Uploading media

You can let your users upload images, audio and video via the Nymbol API, and attach them to a specific asset. Like comments, they'll go into an approval queue for the content curators to look through.

Uploading content is a little bit trickier than posting comments and ratings, but depending on your platform, probably not that much more complex. Mainly it involves using a different enctype as you'll be dealing with ASCII (or unicode) and binary data within the same request.

A POST request for a photo would look like this:

POST /api/manager/collection/<collection_id>/assets/<asset_id>/ratings.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
X-Platform: iphone
X-Device: 9de7219d-c8cf-45d1-b8ab-c6a440071f3f
enctype: multipart/form-data

-----------------------------7d6783b2088e
Content-Disposition: form-data; name="guest_name"
Geoff Guestington
-----------------------------7d6783b2088e
Content-Disposition: form-data; name="guest_email"
geoff@guestington.com
-----------------------------7d6783b2088e
Content-Disposition: form-data; name="kind"
image
-----------------------------7d6783b2088e
Content-Disposition: form-data; name="media"
Content-Type: image/jpeg
...

The ellipses here represent the binary data for the image. Hopefully your platform's HTTP library will include the ability to pass binary data to a dictionary or array, but currently iOS and Android don't appear to support this (there are however some useful resources which you'll find in the Further reading section below).

As with posting comments, the fields you'll need so submit are:

  • guest_name: the name of the user submitting the comment
  • guest_email: the email address of the commenter

You'll also need to submit the following:

  • kind: the type of media to upload. This should be image, audio or video
  • media: the binary-encoded image, piece of audio, etc

We recommend submitting MPEG video, JPEG images and MP3 audio, at the highest quality you're prepared for your users to transfer over wifi or 3G, but bear in mind that video files will be converted to a maximum size of 640x360, so your quality settings should take that into account so you don't end up sending large files that will only get compressed.

Video is automatically queued for conversion by the system. If the video fails to convert, the content curator for that collection will be notified. If it's successful, it will be placed under review for the curators to check over and approve or reject. Images are converted straight away.

Notice the Content-Type declaration as part of the media field. This is important, as it tells the API what kind of content to expect. If it doesn't recognise the content type, it will throw an error.

If you're building a cross-platform app, why not take a look at Appcelerator Titanium? Our first case study, BAApp Walking Architecture was built in Titanium, and lets users upload photos. Titanium's HTTP library is very simple in comparison to the native ones, and it provides useful callbacks for monitoring the progress of the upload. We're not affiliated with Titanium, this is just a friendly tip.

Submitting links and text resources

If you want to, you can also allow your users to submit text resources and links. This is simpler than posting median as we return to using URL-encoded form data. Text resources are submitted like this:

POST /api/manager/collection/<collection_id>/assets/<asset_id>/resources.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
X-Platform: iphone
X-Device: 9de7219d-c8cf-45d1-b8ab-c6a440071f3f
enctype: application/x-www-form-urlencoded

kind=text
&description=The+body+of+the+resource

Links are very similar:

POST /api/manager/collection/<collection_id>/assets/<asset_id>/resources.json
Host: nymbol.co.uk
Authorization: b4b6bfb2347932fd9cfa9642b1c1a7f7
X-Platform: iphone
X-Device: 9de7219d-c8cf-45d1-b8ab-c6a440071f3f
enctype: application/x-www-form-urlencoded  
Accept-Language: en-bb

kind=link
&url=http%3A%2F%2Fexample.com
&description=The+body+of+the+resource

Descriptions

All resources can have text accompanying their media. In the case of text resources, there is no media, only text; similarly link resources only have a description but their other attributes can vary depending on whether the URL being posted points to embeddable content, like a YouTube video or Flickr image. See the Resources guide for more on that topic.

The description field is useful for things like image uploads, which might have extra comments attached to them.

Use the Accept-Language HTTP header to set the language that the user is writing their content in. This will be preserved in the system, allowing multiple-language versions of the same text to be posted for the same resource, just like content curators can set multiple-language versions of asset descriptions. See Setting the language in the Assets guide for more on localisation.

Further reading

Next guide: Neighbourhoods → ← Previous guide