Skip to content

API V2 Progress

Jump to bottom Edit New page
Gray Bowman edited this page Mar 12, 2015 · 60 revisions

Error Handling

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 api/2/users/

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"
}

POST api/2/sessions/

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, starttime="2015-01-01T00:00", and client_type="iOS 8.1" would produce a result similar to:

{
    "session_id": 51,
    "language": "en"
}

GET api/2/projects/:id/

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."
}

GET api/2/projects/:id/tags/

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"
        }
    ]
}

GET api/2/projects/:id/assets/

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
    }
]

POST api/2/streams/

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
}

PATCH api/2/streams/:id/

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."
}

POST api/2/streams/:id/heartbeat/

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.

POST api/2/streams/:id/next/

Advances to the next sound.

Access permissions:

  • Authenticated (Requires token)

Example:

A request to "api/2/streams/1/next" would produce a response code of 200 with no response body.

GET api/2/streams/:id/current

Access permissions:

Authenticated (Requires Token)

Example:

A GET request to "api/2/streams/64/current" would produce a result similar to:

{
    "asset_id": 17
}

POST api/2/envelopes/

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": 17
}

PATCH api/2/envelopes/:id/

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
  • 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, and a binary .wav file in the field "file" would produce a result similar to:

{
    "asset_id": 17
}

POST api/2/assets/

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
  • 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:

{
    "asset_id": 23
}

GET api/2/assets/

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
    },
]

GET api/2/assets/:id/

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
}

In Development

Voting on assets api/2/assets/:id/vote/

Add a custom footer
Add a custom sidebar
Clone this wiki locally