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.
Search 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. Response: • 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
Comments URL Path: /api/world-record/comments/<id> HTTP Method: GET Request Parameters: None Response: An
array of Comment objects
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
States/Provinces: 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
Countries: 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: · 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):
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.
User: • 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>)
Media: • url - String, URL to the media • mime_type - String, The MIME type of the media
Comment: • user* - The user who posted the comment • text - Text of the comment • created_at - The date the comment was created at
Person: • first_name - First name of the Person • last_name - Last name of the Person • email - E-mail address of the Person
Record: • Description - String, the name of the record • PrimaryImage • Thumbnail • 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 |
 | |
|
Home >
URDB API |