-
Notifications
You must be signed in to change notification settings - Fork 20
API V2 Progress
DRF has a standard way of returning error conditions in which the HTTP status code is the measure of success, and the JSON response body includes a single "detail" field with the cause of error. In the interest of not fighting the framework, the following endpoints operate in the same manner. Errors will present a HTTP 400 BAD REQUEST, along with a detail field for explanation. Success will be in the form of a HTTP 200, along with a response body filled with relevant resulting data.
POST account creation parameters and obtain a token. The only API endpoint accessible without a token:
- device_id - Required to generate a new account, Android/iOS device specific id generated by the device
- client_type - Required to generate a new account, device type metadata. Examples: iPhone, iPad, Samsung Galaxy S4, etc.
Note: Roundware apps generate initial user accounts for mobile devices. Users will be able to claim their accounts or register on initial startup in the future.
Access permissions:
- Anonymous
Example:
A request to "api/2/users/" with post params of device_id=12345 and client_type="iPad" would produce a result similar to:
{
"username": "12345",
"token": "2517321c7babab0f6259a895d82f510e0d0db34e"
}Creates a new user session for a project, with localization
Parameters:
- project_id - Required. The id of the project to associate this session with.
- client_system - Required. Device system metadata. Examples: Android 4.1.2, iPhone OS-7.0.4, etc. Stored on session basis because device systems can change over time.
- timezone - Optional. Defaults to '0000' if not provided. Device timezone in format Z - RFC822 GMT format (e.g. "-0800")
- language - Optional. Defaults to 'en' if not provided. Each user must have a language for localization purposes. ISO 2-character language code (i.e. 'en', 'fr', 'es' etc). Stored on session basis because device language can change between sessions.
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/sessions/" with post params of project=1, timezone="-500", and client_type="iOS 8.1" would produce a result similar to:
{
"session_id": 51,
"timezone": "-0500",
"language": "en",
"client_system": "iOS 8.1",
"project_id": 1,
}Retrieves information about a project
Request Query Parameters
- session_id - Required. Allows project text to be localized based on language of session
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/projects/1/?session_id=53" would produce a result similar to:
{
"project_id": 1,
"name": "Test Project",
"latitude": 1,
"longitude": 1,
"pub_date": "2011-12-06T16:06:32",
"audio_format": "mp3",
"auto_submit": true,
"max_recording_length": 30,
"listen_questions_dynamic": false,
"speak_questions_dynamic": false,
"sharing_url": "http://example.org/r/eid=[id]",
"out_of_range_url": "http://example.org:8000/mg_outofrange.mp3",
"recording_radius": 20,
"listen_enabled": true,
"geo_listen_enabled": true,
"speak_enabled": true,
"geo_speak_enabled": true,
"reset_tag_defaults_on_startup": true,
"repeat_mode": "stop",
"files_url": "http://example.org/dev/rw-base/webview/rw.zip",
"files_version": "1",
"audio_stream_bitrate": "128",
"ordering": "random",
"demo_stream_enabled": false,
"demo_stream_url": "http://example.org:8000/scapes1.mp3",
"sharing_message": "Check out this awesome recording I made using Roundware!",
"out_of_range_message": "You are out of range of this Roundware project. Please go somewhere within range and try again. Thank you.",
"legal_agreement": "Herein should be the brief legal agreement that participants need to agree to in order to make and submit a recording to a Roundware project.",
"demo_stream_message": "You are out of range of this Roundware project. Please go somewhere within range and try again. Thank you."
}Retrieves information about a project
Request Query Parameters:
- session_id - Required. Allows tags to be localized based on language of session
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/projects/1/tags?session_id=53" would produce a result similar to (shortened for brevity):
{
"speak": [
{
"code": "gender",
"name": "What gender are you?",
"order": 1,
"header_text": "What gender are you?",
"defaults": [ ],
"options": [
{
"relationships": [
3,
4,
5,
],
"value": "male",
"description": "male",
"shortcode": "male",
"loc_description": "",
"data": "class=tag-one",
"order": 2,
"tag_id": 3
},
{
"relationships": [
3,
4,
5,
],
"value": "female",
"description": "female",
"shortcode": "female",
"loc_description": "",
"data": "class=tag-one",
"order": 1,
"tag_id": 4
}
],
"select": "single"
}
]
}Retrieves information about a project
Request Query Parameters
- session_id - Optional. Filters based on asset's session
- tag_ids - Optional. Filters based on asset's session
- media_type - Optional. Filters based on asset's session
- envelope_id - Optional. Filters based on asset's session
- language - Optional. Filters based on asset's language
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/projects/1/assets?session_id=64&tag_ids=3,5&media_type=audio&language=en" would produce a result similar to:
[
{
"asset_id": 19,
"latitude": 2,
"longitude": 2,
"filename": "20150309-142000-64.wav",
"file": "/rwmedia/20150309-142000-64.wav",
"volume": 1,
"submitted": true,
"created": "2015-03-09T14:20:43",
"weight": 50,
"description": "",
"session": 64,
"project": 1,
"language": "en",
"tag_ids": [
3,
5
],
"loc_description": [ ],
"media_type": "audio",
"audio_length_in_seconds": 6.31
}
]Creates a new audio stream for a session. The stream_id will match the session_id, and is used in subsequent stream requests.
Request Body Parameters:
- session_id - Required.
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/streams/" with a parameter of session_id=1 would produce a result similar to:
{
"stream_url": "http://localhost:8000/stream1.mp3",
"stream_id": 1
}Modifies an existing stream with either tags, location, or both. Referenced by stream id.
Request Body Parameters:
- tag_ids - one or more tag IDs
OR
- longitude - paired with latitude to modify stream location
- latitude - paired with longitude to modify stream location
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/streams/1/" with a parameter of tag_ids=3 would produce a response code of 200 with no response body.
A malformed or incomplete request may result in a response code of 400 and a response of:
{
"detail": "stream 53 does not exist."
}Informs the server that a stream is still being listened to.
Access permissions:
- Authenticated (Requires token)
Example:
A request to "api/2/streams/1/heartbeat" would produce a response code of 200 with no response body.
Fades out current asset and advances to the next asset in the playlist.
Access permissions:
- Authenticated (Requires token)
Example:
A request to api/2/streams/1/skip/ would produce a response code of 200 and body:
{
"success": true
}
Fades out current asset and advances to the asset specified in the POST body.
Request Body Parameters:
asset_id
Access permissions:
- Authenticated (Requires token)
Example:
A request to api/2/streams/1/playasset/ would produce a response code of 200 and body:
{
"success": true
}
Fades out current asset and plays it again in accordance with audiotrack parameters.
Access permissions:
- Authenticated (Requires token)
Example:
A request to api/2/streams/1/replayasset/ would produce a response code of 200 and body:
{
"success": true
}
Fades out current asset and prevents any new assets from being added to audiotrack while still continuing to update playlist.
Access permissions:
- Authenticated (Requires token)
Example:
A request to api/2/streams/1/pause/ would produce a response code of 200 and body:
{
"success": true
}
Undoes api/2/streams/:id/pause/ by immediately adding top playlist asset to audiotrack and continuing per normal operation.
Access permissions:
- Authenticated (Requires token)
Example:
A request to api/2/streams/1/resume/ would produce a response code of 200 and body:
{
"success": true
}
Access permissions:
Authenticated (Requires Token)
Example:
A GET request to api/2/streams/64/current would produce a result similar to:
{
"asset_id": 20,
"start_time": "2015-03-13T12:00:09",
"duration_in_stream": 2936,
"current_server_time": "2015-03-13T12:01:39.883486"
}Returns a boolean representing whether a stream of certain stream_id is currently active.
Access permissions:
Authenticated (Requires Token)
Example:
A GET request to api/2/streams/64/isactive would produce a result similar to:
{
"stream_id": 64,
"active": true
}if the stream was currently active.
Creates a new envelope
Request Body Parameters:
- session_id - Required
Access permissions:
- Authenticated (Requires Token)
Example:
A POST request to api/2/envelopes/ with a body parameter of session_id=64 would produce a result similar to:
{
"envelope_id": 22,
"session_id": 64,
"created": "2015-03-27T12:13:54.712315",
"assets": [ ]
}Add an existing asset to an envelope, or create a new asset from included file and add to envelope
Request Body Parameters:
- session_id - Required. The session identifier
- asset_id - Required OR file. The identifier for the asset to add to the envelope
- file - Required OR asset_id. A file uploaded in the request.
- media_type - Optional, defines media type for asset, defaults to 'audio'
- latitude - Optional, sets location of asset
- longitude - Optional, sets location of asset
- description - Optional, text description of asset
- tag_ids - Optional, sets tags of asset
- submitted - Optional
Access permissions:
- Authenticated (Requires Token)
Example:
A PATCH request to "api/2/envelopes/6/" with a body parameter of session_id=64, latitude=1, longitude=1, and a binary .wav file in the field "file" would produce a result similar to:
{
"description": "",
"latitude": 1,
"longitude": 1,
"filename": "20150318-115409-64.wav",
"file": "/rwmedia/20150318-115409-64.wav",
"volume": 1,
"submitted": true,
"created": "2015-03-18T11:54:09.447408",
"weight": 50,
"project": 1,
"language": "en",
"loc_description": [ ],
"asset_id": 29,
"media_type": "audio",
"audio_length_in_seconds": 2.94,
"tag_ids": [ ],
"session_id": 64
}Create a new asset
Request Body Parameters:
- session_id - Required. The session identifier
- asset_id - Required OR file. The identifier for the asset to add to the envelope
- file - Required OR asset_id. A file uploaded in the request.
- media_type - Optional, defines media type for asset, defaults to 'audio'
- latitude - Optional, sets location of asset
- longitude - Optional, sets location of asset
- description - Optional, text description of asset
- tag_ids - Optional, sets tags of asset
- submitted - Optional
Access permissions:
- Authenticated (Requires Token)
Example:
A POST request to "api/2/assets/" would produce a result similar to:
{
"description": "",
"latitude": 1,
"longitude": 1,
"filename": "20150312-111939-64.wav",
"file": "/rwmedia/20150312-111939-64.wav",
"volume": 1,
"submitted": true,
"created": "2015-03-03T10:48:09",
"weight": 50,
"project": 1,
"language": "en",
"loc_description": [ ],
"asset_id": 10,
"media_type": "audio",
"audio_length_in_seconds": 2.94,
"tag_ids": [ ],
"session_id": 64
}Retrieve list of assets, filtered by query parameters
Request Query Parameters:
- project_id - Optional
- session_id - Optional
- tag_ids - Optional
- media_type - Optional
- language - Optional
- envelope_id - Optional
- longitude - Optional
- latitude - Optional
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to "api/2/assets/?project_id=1&media_type=audio&language=en" would produce a result similar to:
[
{
"asset_id": 19,
"latitude": 2,
"longitude": 2,
"filename": "20150309-142000-64.wav",
"file": "/rwmedia/20150309-142000-64.wav",
"volume": 1,
"submitted": true,
"created": "2015-03-09T14:20:43",
"weight": 50,
"description": "",
"session": 64,
"project": 1,
"language": "en",
"tag_ids": [
3,
5
],
"loc_description": [ ],
"media_type": "audio",
"audio_length_in_seconds": 6.31
},
]Retrieve a specific asset by its id
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to "api/2/assets/10/" would produce a result similar to:
{
"asset_id": 10,
"latitude": 1,
"longitude": 1,
"filename": "20150303-104806-64.wav",
"file": "/rwmedia/20150303-104806-64.wav",
"volume": 1,
"submitted": true,
"created": "2015-03-03T10:48:09",
"weight": 50,
"description": "",
"session": 64,
"project": 1,
"language": "en",
"tag_ids": [ ],
"loc_description": [ ],
"media_type": "audio",
"audio_length_in_seconds": 2.94
}Submits a vote (like, flag, rate) for an asset. Returns the new vote object, as well as an updated vote count for the asset.
Request Body Parameters:
- session_id - Required
- vote_type - Required. One of 'flag', 'like', or 'rate'
- value - Optional, but required for the vote_type 'rate'. An integer value
Access permissions:
- Authenticated (Requires Token)
Example:
A POST request to "api/2/assets/10/votes/" with parameters of session_id=64, vote_type=rate, and value=5 would produce a result similar to:
{
"value": 5,
"type": "rate",
"vote_id": 4,
"asset_id": 10,
"session_id": 64,
"asset_votes": [
{
"total": 1,
"type": "rate",
"avg": 5
},
{
"total": 1,
"type": "flag"
},
{
"total": 2,
"type": "like"
}
]
}Retrieve vote counts for an asset
Request Parameters: None
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to "api/2/assets/10/votes/" would produce a result similar to:
[
{
"total": 1,
"type": "rate",
"avg": 5
},
{
"total": 1,
"type": "flag"
},
{
"total": 2,
"type": "like"
}
]Retrieves filterable list of events
Request Parameters:
- session_id - Optional
- event_type - Optional, matches on contents in 'icontains' manner
- server_time - Optional, matches on datetime in 'startswith' manner
- server_time__lt - Optional, matches on a server time less than one given
- server_time__gt - Optional, matches on a server time greater than one given
- latitude - Optional, matches on latitude 'startswith'
- longitude - Optional, matches on longitude 'startswith'
- tag_ids - Optional, comma delimited String of tags. Matches on any given tag
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/events/, with query parameters session_id=64, server_time__lt=2015-02-27 would produce a result similar to:
[
{
"server_time": "2015-02-26T15:11:06",
"client_time": null,
"event_type": "request_stream",
"data": null,
"latitude": null,
"longitude": null,
"tags": null,
"event_id": 92,
"session_id": 64
},
{
"server_time": "2015-02-26T15:11:36",
"client_time": null,
"event_type": "modify_stream",
"data": null,
"latitude": 1,
"longitude": 1,
"tags": null,
"event_id": 93,
"session_id": 64
}
]Creates and logs a new event
Request Body Parameters:
- session_id - Required.
- event_type - Required
- client_time - Optional
- data - Optional
- latitude - Optional
- longitude - Optional
- tag_ids - Optional, comma delimited String of tag ids.
Access permissions:
- Authenticated (Requires Token)
Example:
A POST request to api/2/events/ with body parameters of session_id=64,event_type=test would produce the result:
{
"server_time": "2015-03-16T12:15:27.865518",
"client_time": null,
"event_type": "test",
"data": null,
"latitude": null,
"longitude": null,
"event_id": 242,
"session_id": 64,
"tag_ids": null
}Retrieves an event by ID
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/events/242 with a query string parameter of session_id=64 would produce the result:
{
"server_time": "2015-03-16T12:15:27.865518",
"client_time": null,
"event_type": "test",
"data": null,
"latitude": null,
"longitude": null,
"event_id": 242,
"session_id": 64,
"tag_ids": null
}Retrieves a filterable list of listenevents
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/listenevents/ with a query string parameter of session_id=64 would produce the result:
[
{
"id": 1,
"duration_in_seconds": 6.31,
"start_time": "2015-03-13T12:00:04",
"session_id": 64,
"asset_id": 19
},
{
"id": 2,
"duration_in_seconds": 2.94,
"start_time": "2015-03-13T12:00:09",
"session_id": 64,
"asset_id": 20
}
]Retrieve listenevent by id
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/listenevents/12/ would produce the result:
{
"id": 1,
"duration_in_seconds": 6.31,
"start_time": "2015-03-13T12:00:04",
"session_id": 64,
"asset_id": 19
}Retrieves filterable list of tags
Request Parameters:
- session_id - Optional. If provided, returns localized strings in the language of the session. Defaults to 'en'
- tag_category_id - Optional
- value - Optional, matches exactly
- description - Optional, matches on icontains
- data - Optional, matches on icontains
- filter - Optional, exact match
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/tags/ with a parameter of value=male would produce the result:
[
{
"value": "male",
"description": "male",
"data": "class=tag-one",
"filter": "",
"tag_category": 3,
"loc_description": null,
"loc_msg": "male",
"relationships": [
3,
4,
5,
8,
9,
22,
23
],
"tag_id": 3
}
]Gets a tag by id
Request Parameters:
- session_id - Optional. if passed, used to localize the tag with the session language
Access permissions:
- Authenticated (Requires Token)
Example:
A GET request to api/2/tags/3/ with a parameter of session_id=100 would produce the result:
{
"value": "male",
"description": "male",
"data": "class=tag-one",
"filter": "",
"tag_category": 3,
"loc_description": null,
"loc_msg": "male",
"relationships": [
3,
4,
5,
8,
9,
22,
23
],
"tag_id": 3
}Remaining APIv2 calls