Home‎ > ‎


Version 1.9


This document outlines a proposal for a RESTful web services interface to the URDB web application. While the API is tailored to the specific needs of the iPhone application as collaboratively designed by the URDB and Two Toasters teams, it is generic enough to provide a generally available client API. The API will be implemented via simple HTTP form encoded requests and JSON formatted responses.


Successful responses will return 200 (OK) responses for read operations and 201 (Created) responses for submission of data. When an error occurs, the server will respond with a 422 (Unprocessable Entity) response if the error is the result of invalid client input. For client errors, the server will return a JSON hash containing an errors key with a value that is an array of strings describing the errors encountered while processing the request. These messages should be human readable and the entire request should be evaluated such that all errors are returned at once so that the User can correct all invalid input at once.


I.  API Authorization

            Access to the API will be restricted via an API key HTTP header. Failure to provide a valid API key will result in an HTTP 403 (Forbidden) response. The header must be provided as X_URDB_API_KEY. Our recommendation is to use a SHA1 or UUID as the value for the key, but any sufficiently long and obscure string will suffice.


II. User Authentication

            The API will support two authentication mechanisms: URDB site-specific accounts and authentication via Facebook Connect. Once authentication has been completed, the system will issue an authentication token to the authenticated client. This token value must be sent with all subsequent API calls that require authentication via the HTTP header X_URDB_AUTH_TOKEN. Like the API key, we recommend the use of a SHA1 or a UUID as the value.

            Facebook connect authentication occurs via intermediary recalls to Facebook. In this request path, Facebook will handle the authentication and then redirect the user to a destination URL to obtain authentication from the URDB service. The request portion outline below will not occur, but the end response will be the same.


Login API call

            URL Path: /api/login

            HTTP Method: POST

            Request Parameters:

  EmailAddress - String [Also expose “Email”, can be used instead of EmailAddress for consistency with Create User]

  Password - String      

            Response (JSON hash):

  AuthToken - String

   Handle – String. User user handle (unique identifier) for the authenticated User.

  Name – String. User’s Name (First Last)


Login/Register API call for Facebook

If user exists in URDB, URDB AuthToken returned.  If the user does not exist in URDB, they will have a Person record created and a URDB AuthToken will be returned.

            URL Path: /api/loginFacebook

            HTTP Method: POST

            Request Parameters:

·         AccessToken – String. Facebook AccessToken.

·         ExpirationDate – String. Facebook AccessToken expiration.

Response (JSON)

·         AuthToken – String

·         Handle – String

·         Name – String.  User’s Name (First Last)

·         Email – String.

Error Conditions

·         422 - Invalid Email; format or used by another User

·         422 – Age; Must be 14 or older

·         403 – Invalid or expired access token


III.            Read Operations

            Read operations on the World Record API does not require authentication. The read API calls defined below allow access to existing data within the URDB system and provide everything necessary to create a rich interface to URDB.


Retrieve User Details

            URL Path: /api/user/<handle>

            HTTP Method: GET

            Request Parameters: None

            Response: A JSON User object defined below.



            URL Path: /api/world-record/search/?q=<query>[&startIndex=0&rowCount=10]

            HTTP Method: GET

            Request Parameters:

  q – String, required, none empty.

  startIndex – Optional, zero based index representing the starting point for result set.

  rowCount – Optional, number of records to return.  Max is 20.  Default is 20.


  TotalRecordCount – The total number of records matching the query.  To be used for client side paging.

  A hash containing an element ‘Records’ that is an array of ‘Record’ objects detailed below.


Retrieve Record Details

            URL Path: /api/world-record/<RecordId>

            HTTP Method: GET

            Request Parameters: None

            Response: A JSON World Record object defined below.


Past Record Holders

            URL Path: /api/world-record/holders/<RecordId>

            HTTP Method: GET

            Request Parameters: None

            Response: An array of User objects



            URL Path: /api/world-record/comments/<id>

            HTTP Method: GET

            Request Parameters: None

            Response: An array of Comment objects
            Note: id is polymorphic in that it can be the id for a user, record, etc.


Record Attempts:

            URL Path: /api/world-record/attempts/<RecordId>

            HTTP Method: GET

            Request Parameters: None

            Response: An array of Record Attempt objects


Record Count by Tag:

            URL Path: /api/world-record/count/<tag>

            HTTP Method: GET

            Request Parameters: None

            Response: The count of approved records for the supplied tag



            URL Path: /api/stateprovinces

            HTTP Method: GET

            Request Parameters: countryId – optional param that filters results by country

            Response: An array of name-value pairs of states and provinces



            URL Path: /api/countires

            HTTP Method: GET

            Request Parameters: None

            Response: An array of name-value pairs of countries


IV.           Write Operations

            Creation of new objects requires that the User be authenticated.


Create User

            URL Path: /api/user

            HTTP Method: POST

            Request Parameters:

·         Name - string

·         Email - string

·         AgeVerified – Boolean

·         Password – string

Response: 201 on success


Create Comment

            URL Path: /api/world-record/comments/<id>

            HTTP Method: POST

            Request Parameters:

  text - The text of the comment

            Response: The Comment object that was created


Create Record Attempt

            URL Path: /api/world-record

            HTTP Method: POST

            Request Parameters:

  RecordId – If the attempt is to break an existing record, RecordId should be provided, else the attempt will be treated as a new record.

  Description – Title of attempt

  Unit – String.  Correlates to the unit “category” – Distance, Time, etc.

  Value – String.  The value that will hold the value and unit.  Note that the unit will not be a URDB unit and needs to be reviewed.

  AttemptDate - Date of the attempt. Format MM/DD/YYYY

  Tags – JSON array of strings

  City - The city / town the attempt was performed in StateProvince** - State / Province attempt was performed in (String name or Int ID)

  Country** - Country the attempt was performed in (String name or Int ID)

  -  Currently we only support one record setter and that would be the logged in user.  No need to send this element unless we modify URDB to support multiple setters.

  WitnessName -  First Name + “ “ + LastName

  WitnessEmail – Email address of the witness

  Pledge – Pledge of honesty, boolean

  AgreeToTerms – Agree to terms of use, boolean

  Criteria – Criteria for the record.  Format is a JSON array ["First Criteria","Second Criteria","Third Criteria"]

  AttemptByName – Optional string.  Allows the logged in user to submit an attempt performed by someone else.

  AttemptByEmail – Required if AttemptByName is provided.

  media - Array of media streams to be uploaded

Response: AttemptPendingId - A unique identifier for the “pending” attempt.  This identifier should be used to upload media.


Upload Media for Attempt

            URL: /api/world-record/media

            HTTP Method: POST


            Request Parameters:
                 Note: multipart/form-data will be used.  After the boundry that separates the AttemptPendingId param, the following is expected (Token {0} to be replaces with filename):
Content-Disposition: form-data; name=\"file\"; filename=\"{0}\"\r\n Content-Type: application/octet-stream\r\n\r\n

·         AttemptPendingId – Unique identifier returned from Create Record Attempt used to associate the media to the Attempt.

·         The Media to be uploaded.  These bytes will be withing the application/octet-stream part. At the end of this section the following is expected (Where “boundry” is a series of Unicode chars):
\r\nContent-Disposition: form-data; name=\"Upload\"\r\n\r\nSubmit Query\r\n--" + boundary + "--"


V.            Data Types

            The data types defined below are simple JSON hashes that define domain objects. They may be sent back as a sub-hash of an existing response body or may represent the total response body where appropriate.



   Email - Not including for privacy reasons.Handle

  Name - String, Full name of the User

  CurrentRecords - Integer, the number of records the user holds

  BrokenRecords - Integer, the number of records the user has beaten

  FailedRecords - Integer, the number of failed record attempts

  DeniedRecords - Integer, the number of denied record attempts

  PendingRecords - Integer, the number of pending record attempts

  WitnessedAttempts - Integer, the number of attempts the User has witnessed

  AvatarImageUrl - String, URL of the user’s avatar image

  Url - String, URL to full details of the user (i.e. /api/users/<username>)



  url - String, URL to the media

  mime_type - String, The MIME type of the media



  user* - The user who posted the comment

  text - Text of the comment

  created_at - The date the comment was created at



  first_name - First name of the Person

  last_name - Last name of the Person

  email - E-mail address of the Person



  Description - String, the name of the record



  RecordId – Integer, an identifier to be used when submitting an attempt to break the current record.

  Urn - String, an identifier suitable for use in a URL

  UnitOfMeasure - String, a description of the units the record is set at (i.e. balloons, balls)

  Value - String, the current value for the record (i.e. “230”)

  Tags - Array of strings describing tags applied to this record

  Criteria – A subhash of strings representing the criteria for this record.

  RecordCreator* - A subhash of Users details about the record holder. TBD

  RecordHolder* - A subhash of User details about the current record holder.

  media - Array of Media objects for media associated with the record (PENDING?) TBD

  AttemptDate - String, timestamp the winning record attempt was set at (PENDING?)

  AttemptId – the unique identifier for the Attempt

  RecordHolderName – string, eliminate need to call back to api just to get name.

  RecordCreatorName – string, eliminate need to call back to api just to get name.

  VideoLocation – The full Url to the video documentation

  Link – Full URL to the Record

  InternalRating – Integer.  An InternalRating greater than or equal to 6 indicates a “favorite” or “editor’s pick”. Records with a rating less than 3 will not appear on the site.


* - Starred items defined as subhashes could be passed as URL’s instead to make responses payloads lighter at the expense of additional requests to fetch the data.

** - Requires conversion from string to URDB internal representation (Integer, etc.) – potential for no match found if user keys in this value. Pre-shortened link (e.g. http://r.urdb.org/5S)

Feel free to email the team directly at hello at urdb dot org