• Overview
• Key concepts
  • Contribution submission flow
  • Media processing
    • Supported media formats
  • Moderation and publishing
  • Geolocation
    • User supplied locations
    • Geocoding
    • Redacting user supplied locations
  • Dates
  • Use of HTTPS
• Domain model
• Endpoints
• Authentication
  • Obtaining an access token
  • Using an access token
  • Custom authentication
  • Client authorisation
• Developer resources
  • Swagger
  • SDKs
    • Android
    • Swift
  • AMP
  • Reference web front end
  • Reference Android app

What does the Contribly API do?

The Contriby API is a RESTful API which provides a set of end points for accepting, moderating and publishing user submitted content.

The API provides developers with a ready made system to manage various aspects of the user generated content (UGC) life cycle:

• Public end points for the submission of the contribuitions from client side website code, server side code or mobile apps.
• Media processing; identification and conversion of submitted media files.
• Archiving of original submission media.
• Managing the visibility of moderated and unmoderated content.
• Distribution of published contributions to docroots, CDNs and external services such as YouTube.
• Public facing JSON API for serving moderated content back to your websites and apps.

The end to the submission of a contribution would typically involve several steps and corresponding API calls; namely authentication, media upload and submission of the contribution.

An access token needs to be obtained before the client can begin to compose a contribution.

The client authenticates the end user and obtains an API access token by making a grant token call to the token end point.

The client uses the user's access token to upload any media files associated with their contribution by posting them to the media end point. This needs to be an authenticated call so that the media files can be assigned the correct ownership.

The submitting application receives a sequence of media elements with unique identifiers in return.

The client composes a contribution object appending any previously uploaded media elements.

This contribution is submitted to the contributions end point using the same access token that was used to upload the media elements.

The contribution goes into the moderation queue and is visible to moderators in the moderation tool.

An end to end example of the submission flow is visible in the submission controller of the reference application.

Contriby provides several media processing functions.

• Identificating type of a raw submitted file.
• Media orientation correction (EXIF rotation) and meta data extraction
• Scaling and cropping of images and videos
• Stripping of meta data from public static assets
• Publishing of static assets to docroots and CDNs

Media processing is an asynchronous process.

The media submission end point will immediately return a media object but this object may not be fully populated. Attributes of the media element which are time consuming to produce will be populated as they become available.

POSTs to the submit media endpoint return HTTP 202 Accepted with a partially populated media object. A response is returned as soon as the submission details and raw file have been persisted and a usable id has been assigned to the media object.

Media elements should be considered immutable. The original media file will be preserved. Edits to media elements (such as rotations) are expressed using the media usage domain object.

The client is free to reference the newly created media id in contributions as soon as it is returned.

The more time consuming media processing operations begin in the background. Subsequent GET requests for the media object will show progressively more media attributes as they become available.

After submission, media files are first scanned to detect the content type. If a supported file format is detected scaled image and video artifacts are produced and appended to the media object.

Contribly is able to process most standard media formats.

JPEG, PNG, HEIC, GIF (single frame), WebP and BMP images can be submitted.

Images can be output as JPEG or PNG files. The max file size is 20MB.

MP4, MPEG1, Quicktime, FLV, theora and webm formatted videos can be submitted. Video sizes up to full HD are supported. This includes videos originally shot on iOS and Android devices. The max file size is 100MB.

Videos are output as HTML5 compatable MP4 files.

New contributions are held in the moderation queue until they are reviewed and approved by a moderator using the Contribly moderation tool.

Once approved the contribution becomes visible on the public contributions end points and it's media artifacts are published to public URLs.

Users may submit contribution location information as a latitude/longitude pair, a Google place id or an OpenStreetMap id.

Google place and OSM ids arguably preserve more context that a simple latitude/longitude point. User interfaces which use of Google of OpenStreetMap location suggestions should capture the Google or OSM id and pass them to Contribly if possible.

User supplied latitude/longitude locations are geocoded into human readable locations. OpenStreetMap Nominatim is the default geocoding service.

A user's precise location may be deemed to be sensitive. The geo resolution setting of an assignment can be used to obscure this potentially sensitive information.

The assignment geo resolution effects publicly visible location of contributions as follows:

Rounded locations are geocoded to ensure that the original precise location is not preserved in the location name. The unaltered user supplied location remains visible to moderators in the user supplied location block of the moderation tool.

All dates and date times are output in ISO8601 date time format with a UTC time zone (including milliseconds). All date and date time field inputs are expected to be in this format.

i.e.

2016-01-27T12:24:33.406Z

The equivalent Joda formatter is ISODateTimeFormat.dateTime

To protect user data the Contribly API and tools use HTTPS end to end. API end points and the moderation tools are only accessible via HTTPS.

The Contribly widgets, moderation tools and their related CDNs transfer all user data over secure HTTPS connections.

The known expectations to this policy are:

• The map tiles for the Contribly map widget are served over HTTP. These tiles are not specific to end users. HTTP is used to improve caching. HTTPS tile support is available on request.

The Contribly domain model can be considered a glossary of terms which are used to describe various types of data in the system.

Represents a specific size or format a media object. Original media files submitted by users will be converted and scaled into the required artifact formats which an approved contribution is published.

An artifact format describes an output format for the static assets which will be produced when a contribution's media elements are published.

For example, a particular application may require images to be scaled to fit a mobile screen. This requirement can be expressed using an artifact format. The current artifact formats for your Contribly instance can be viewed in the Settings / Publishing section of the Contribly moderation tool.

A assignment is a topic your users can contribute to. Assignments can be used to frame your call outs for contributions.

An authority record represents an access token which can be used preform authenticated actions (such as submitting contributions or moderating content).

An API client (or app). Authenticated calls the the API are made using an authority obtained using a client.

A flag represents a potential issue with a live contribution. Flags allow other users or members of the public to bring their concerns about a contribution to the attention of moderators.

An end user form response submission.

In some contexts precise location information contained in user submissions may be sensitive. The assignment geo resolution setting provides a way to control the publicly visible location information attached to user submissions to that assignment. The original user submitted location remains available to moderators.

Represents a single media element such as an image or video file.

Media elements can be considered to be large immutable. Fields may be appended to a media element during the content type detection and artifact production parses but once set cannot be altered. The appearance of a media element can be manipulated by editing it's corresponding media usage.

Represents a usage of a given media element, potentially with edits applied to it.

A workflow action taken by a moderator on a specific contribution.

ie. Approve, rejected etc

Typically a moderation action would be used to change the moderation state of a contribution.

The current moderation state of a given contribution.

ie. Approved, rejected, referred to legal etc.

Tags can be applied to contributions and assignments.

A tag set represents a grouping of related tags.

API end points are also documented as a Swagger defination (see developer resources).

Documentation end point which returns a list of the currently available artifact formats.

Lists assignments.

Requires user authentication.

Submit a assignment

The request body should contain a JSON representation of your new assignment.

Display a single assignment by id

Create an assignment.

Lists contributions.

Requires user authentication.

Submit a contribution.

Sample request

Authorization: Basic an-access-token
Content-Type: application/json

{
    "headline":"Test with media element 41891db7-5791-4b7d-a795-1544e500aab8",
    "body":"The quick brown fox jumped over the lazy media element",
    "mediaUsages":[
        {
            "media":{
                "id":"e1a75569-fe56-4238-9a99-c3bbcd848eb7"
            }
        }
    ]
}

Sample response

{
   "id" : "6768e8b0-5c70-40f4-b2c3-2767fe043742",
   "headline" : "Test with media element da19a985-fb35-41d9-b761-a381ebc67f2b",
   "body" : "The quick brown fox jumped over the lazy media element",   
   "urlWords" : "bc69cabf-8cdc-4309-ad2f-4baa3b1863b7",
   "likes" : 0,
   "mediaUsages" : [
      {
         "id" : "9c44feec-9bc1-4578-aee2-1dc45b415037",
         "media" : {
            "id" : "c43823f9-4eeb-47e4-8ca4-041e1f964cbd"
         },
         "artifacts" : [],
      }
   ],
   "created" : "2016-10-16T16:06:36.883Z",
   "via" : {
      "authority" : {
         "user" : {
            "username" : "dfb6b7f0-4645-4bde-9d32-09a71b34c729",
            "registered" : "2016-10-16T16:06:36.509Z",
            "via" : {
               "id" : "test-client",
               "name" : "Test client"
            },
            "displayName" : "dfb6b7f0-4645-4bde-9d32-09a71b34c729"
         },
         "client" : {
            "id" : "test-client",
            "name" : "Test client"
         }
      }
   }
}

If the new contribution JSON was in a local file, the corresponding curl command line would be:

curl -i  -H "Authorization: Bearer an-access-token" -H "Content-Type: application/json" -X POST --data "@contribution.json" https://api.contribly.com/1/contributions

Returns a single contribution.

Optional user authentication.

Raise a flag against this contribution (ie. offensive content etc).

The request body should contain a JSON representation of a flag object.

If a a user authentication token is included the flagging user will be recorded. Anonymous flags can be raised by making an unauthenticated request.

Like (or unlike if already set) this contribution.

Apply a moderation action to this contribution.

The POST body should contain a JSON moderation history item.

Documentation end point which returns a list of the docroots which your Contribly instance is currently publishing to.

Documentation end point which returns a list of valid flag types which may be assigned to contribution flags.

Requires user authentication.

Post a response to this form.

Expects a form response submission object on the request body.

Returns a single group

Submit a new group.

Requires user authentication.

Accepts a media file presented as the raw binary body of the POST.

Media processing is an asynchronous operation. This end point will immediately return HTTP 202 and a sparsely populated media element. The media element id can used to track its processing state by polling the get media end point. The media element can be immediately referenced in contributions even if all media processing steps have yet complete.

See media processing below.

Sample response

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "id":"8ea47f7e-6097-490f-8458-8d98df557b76"
}

The equilivent curl command is:

curl -i  -H "Authorization: Bearer an-access-token" -X POST --data "@an-image.jpg" https://api.contribly.com/1/media

Retrieve the details for a given media element.

Media processing is an asynchronous operation. After a media element is submitted, fields progressively become available as media processing operations complete.

Sample response

{
	"id" : "8ea47f7e-6097-490f-8458-8d98df557b76",
	"user" : {
		"id" : "7b9f6834-8db9-44d1-bff5-ffae90424ea5",
		"username" : "69fa0804-4e78-4746-8832-3bd10a8ee3ab",
		"displayName" : "69fa0804-4e78-4746-8832-3bd10a8ee3ab",
		"via" : {
			"id" : "test-client",
			"name" : "Test client"
		}
	},
	"metadata" : {
		"Exif Image Height" : "533 pixels",
		"Exif Image Width" : "800 pixels",
		"Date/Time" : "2015:04:23 19:05:19",
		"Model" : "Canon EOS 350D DIGITAL",
		"Exposure Time" : "1/200 sec",
		"md5" : "87e9e12f4e189fac10e7d86d146d5f79",
		"contentType" : "image/jpeg",
		"Max Aperture Value" : "F3.4"
	},
	"contentLength" : 314731,
	"type" : "image",
	"fileExtension" : "jpg",
	"md5" : "87e9e12f4e189fac10e7d86d146d5f79",
	"orientation" : "landscape",
	"contentType" : "image/jpeg"
}

Requires user authentication.

Retrieve a preview of a media element artifact. The call is authenticated to allow the preview of items which have not yet been moderated. The label and extension placeholders should match the label and file extension of an artifact format.

This endpoint supports HTTP Range by byte requests making it compatible with the HTML 5 video components of most major browsers.

Requires user authentication.

Retrieve the original file for a given media item.

Retrieves a list of the available moderation actions.

Lists all tags

Display a single tag

Search for users.

Requires client authorisation.

Register a new user.

The request body should contain a JSON representation of the new user. A client authorisation header must be included to identify your application.

Display a single user's profile

Requires user authentication.

The verify end point can be used to confirm the validately and ownership of an access token.

Verifies an access token. If the Bearer token presented on the Authorization header is valid returns the user details for the user who the token belongs to.

Sample request

POST /1/verify HTTP/1.1
Authorization: Bearer my-token

Curl

curl -v -X POST -H 'Authorization: Bearer my-token' https://api.contribly.cm/1/verify

Sample response

{
   "client" : {
      "name" : "A test client",
      "ownedBy" : "test-owner",
      "id" : "a-test-client-id"
   },
   "user" : {
      "displayName" : "A test user",
      "username" : "testuser",
      "registered" : "2016-08-26T11:00:31.361Z",
      "id" : "test-user-id"      
   },
   "scopes" : [
      "contact-user",
      "create-assignment",
      "edit-assignment",
      "create-form",
      "edit-form",
      "view-form-responses",
      "create-client",
      "edit-client",
      "edit-groups",
      "create-group",
      "edit-profile",
      "edit-smtp",
      "edit-notifications",
      "edit-assignment",
      "edit-assignment-urlwords",
      "preview-media",
      "original-media"
   ]
}

Requires user authentication

Provides a real time activity log via a secure WebSocket connection. Events arrive as JSON objects with the format described below.

All POST and WebSocket end points as well as GET requests which reveal non public data require authentication to identify the user or application making the request.

OAuth2 is the authentication system used. To authenticate a request the end user must first obtain an access token and then append it to their API requests (see using an access token below).

Access tokens are issued to users. To obtain an access token some sort of credentials must be presented and exchanged for an API access token. This exchange is dealt with by the token end point.

Requires client authorisation.

Grants an access token.

Several different grant types are available. The format of the request will vary slightly depending of the choosn grant type.

In all cases, a client authorisation header must be included to identify your application.

If the user is already registered on the system then their username and password credentials can be swapped for an access token, as per the OAuth2 Resource Owner Password Credentials Grant pattern.

The following parameters should be presented in "application/x-www-form-urlencoded" encoded format.

Your API client must also present it's client credentials on the Authorization header (see client authorisation below).

Sample request

Authorization: Basic dtysXC1jbG22bnQ6dGVzdC1zZWNyABC=
Content-Type: application/x-www-form-urlencoded

grant_type=password&username=db4d174c-d801-41a1-b3fd-b13a32bb737a&password=db4d174c-d801-41a1-b3fd-b13a32bb737a

Sample response

{
    "access_token":"77b3fc34-9394-4f6d-ac7d-130a97adf9b4",
    "scope":"full"
}

The equivalent curl command is:

curl -u client-key:client-secret -X POST -d 'grant_type=password&username=username&password=password' https://api.contribly.com/1/token

If the user has granted your local application a valid Facebook access token for a user who has previously registered on the system then this can be used to obtain an API token for that user.

The following parameters should be presented in "application/x-www-form-urlencoded" encoded format.

Your API client must also present it's client authorisation on the Authorization header.

The following parameters should be presented in "application/x-www-form-urlencoded" encoded format.

Your API client must also present it's client authorisation on the Authorization header.

The following parameters should be presented in "application/x-www-form-urlencoded" encoded format.

Your API client must also present it's client authorisation on the Authorization header.

Exchange an existing valid Contribly token for an another with different scopes. Typically used be a client application to obtain a less privileged token for a specific operation (such as viewing media previews). The requested scopes must be a subset of those granted to the initial token.

Your API client must also present it's client authorisation on the Authorization header.

Anonymous contributions should be submitted using an anonymous token. Once the anonymous token has been granted it can be used to contribute in a simular manner to any other token. Anonymous tokens have limited privileges.

Include your access token in your requests by appending a header in this format:

You can check the validity and ownership and available scopes of an access token by submitting it to the verify end point.

Support for third party sign in systems is covered here.

Client authorisation is required for some endpoints (typically those involving the granting of user access tokens). The propose of client authorisation is to allow the calling application to identify itself.

The Contribly API provides a Swagger definition. A Swagger definition describes an API in a machine readable way allowing for easlier integration with third party systems.

The Swagger defination url is:

• https://api.contribly.com/1/swagger.json

API end points can be browsed using Swagger UI:

• https://swagger-ui.contribly.com/

The Swagger Code Generator can be used to generate native API clients for various platforms.

The Contribly submission widget can be integrated into AMP pages.

A working example with source code is available.

Native SDKs can be generated from Contribly API's Swagger definition using Swagger codegen.

Generate the SDK source code using Swagger codegen:

git clone https://github.com/swagger-api/swagger-codegen.git
mvn clean install
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i https://api.contribly.com/1/swagger.json -l java --group-id com.contribly.client --api-package com.contribly.client.api --invoker-package com.contribly.client --model-package com.contribly.client.model --library=okhttp-gson -DserializableModel=true -o /tmp/contribly

Build the client and publish to your local Maven repo:

cd /tmp/contribly
mvn assembly:assembly -DdescriptorId=jar-with-dependencies

The SDK should now be accessible to Android Studio and gradle.

Add the following to your Android project's build.gradle:

compile ('com.contribly.client:swagger-java-client:1.0.0') { transitive true }

Refer to the Contribly reference Android app for a working example of the generated Android SDK integrated into an Android app.

Generate the SDK source code using Swagger codegen:

git clone https://github.com/swagger-api/swagger-codegen.git
mvn clean install
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i https://api.contribly.com/1/swagger.json -l swift -o /tmp/contriby

Add to the Podfile of your Xcode project:

platform :ios, '10.0'
use_frameworks!

target 'My iPhone app' do
    pod 'SwaggerClient', :path => '/tmp/contriby'
end

An example web front end application which demonstrates the main API operations such as authenticating a user and submitting a contribution. This reference application can be browsed on Github:

• https://github.com/contribly/ugc-frontend

This application is a Play Framework app written in Scala. The same API usages should be applicable to other langauges and client side Javascript applications.

A reference Android application demonstrating the Contribly API been used in a mobile setting.

• https://github.com/contribly/contribly-reference-android

The Android app makes use of a client library auto generated from the API's Swagger definition.