API V2 Documentation

The original Roundware V1 API is a mix of RESTful and non-RESTful web service calls returning JSON. In an effort to simplify and standardize, it will be replaced with a fully RESTful V2 API.

API design guide: https://github.com/interagent/http-api-design Migrations and Futureproofing: https://github.com/Prismatic/eng-practices/blob/master/swe/Migrations_and_future_proofing.md Additional best practices notes: https://bourgeois.me/rest/

Milestones

1. Make V2 a functional equivalent of V1. V1 is now deprecated. (In progress)
2. Implement client authentication tokens for mobile clients and user auth for admin web.
3. Implement new V2-only functionality. Determine V1 removal timeline.

Methods

• GET - View the resource
• POST - Create the resource
• PUT - Replace the resource
• PATCH - Update the resource
• DELETE - Delete the resource

Returned in header

api/1/?operation=current_version

GET/POST/PATCH/DELETE api/2/users/:id

New. POST account creation parameters, one of two API endpoints accessible without a bearer token:

• username/email - Required to create a new account.
• password - Required to create a new account.
• 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: POST
• Authenticated: GET, PATCH
• Admin: POST, GET, PATCH, DELETE

Examples:

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

GET/POST/PATCH/DELETE api/2/sessions/:id

Replaces:

api/1/rest/session/:id
api/1/?operation=get_config

Parameters:

• client_system - 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.
• language - Each user must have a language for localization purposes. ISO 2-character language code (i.e. 'en', 'fr', 'es' etc). If blank, the default language of 'en' is assumed. Stored on session basis because device language can change between sessions.

Access permissions:

• Anonymous: None.
• Authenticated: POST
• Admin: GET/POST/PUT/PATCH.

POST api/2/stream

Replaces:

api/1/?operation=request_stream

Access permissions:

• Anonymous: None
• Authenticated: POST
• Admin: POST

PATCH api/2/stream/:id/

Replaces:

api/1/?operation=modify_stream

Access permissions:

• Anonymous: None
• Authenticated: PATCH
• Admin: PATCH

GET api/2/stream/:id/current

Replaces:

api/1/?operation=get_current_streaming_asset

Access permissions:

• Anonymous: None
• Authenticated: GET
• Admin: GET

PUT api/2/stream/:id/current

Replaces:

api/1/?operation=play_asset_in_stream

Access permissions:

• Anonymous: None
• Authenticated: PUT
• Admin: PUT

POST api/2/stream/:id/next

Replaces:

api/1/?operation=skip_ahead

Access permissions:

• Anonymous: None
• Authenticated: POST
• Admin: POST

POST api/2/stream/:id/last

New

Access permissions:

• Anonymous: None
• Authenticated: POST
• Admin: POST

POST api/2/stream/:id/heartbeat

Replaces:

api/1/?operation=heartbeat

Access permissions:

• Anonymous: None
• Authenticated: POST
• Admin: POST

GET/POST/DELETE api/2/events/:id

Replaces:

api/1/?operation=log_event
api/1/rest/event/:id
api/1/?operation=get_events

Access permissions:

• Anonymous: None
• Authenticated: GET, POST
• Admin: GET, POST, DELETE?

GET/POST/DELETE api/2/listenevents/:id

Replaces:

api/1/rest/listeninghistoryitem/:id

Access permissions:

• Anonymous: None
• Authenticated: GET, POST
• Admin: GET, POST, DELETE?

GET/POST/PUT/PATCH/DELETE api/2/envelopes/:id

Replaces:

api/1/?operation=create_envelope

Access permissions:

• Anonymous: None
• Authenticated: GET, POST, PUT, PATCH, DELETE, edit/delete for items owned by user only
• Admin: GET, POST, PUT, PATCH, DELETE

GET/POST/DELETE api/2/envelopes/:id/assets/:id

Replaces:

api/1/?operation=add_asset_to_envelope

Access permissions:

• Anonymous: None
• Authenticated: GET, POST, DELETE, edit/delete for items owned by user only
• Admin: GET, POST, DELETE

GET/POST/PUT/PATCH/DELETE api/2/projects/:id

Replaces:

api/1/rest/project/:id

Access permissions:

• Anonymous: None
• Authenticated: GET
• Admin: GET, POST, PUT, PATCH, DELETE

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

Replaces:

api/1/?operation=get_tags

Access permissions:

• Anonymous: None
• Authenticated: GET
• Admin: GET, POST, DELETE

GET api/2/projects/:id/assets

Replaces:

api/1/?operation=get_available_assets

Access permissions:

• Anonymous: None
• Authenticated: GET
• Admin: GET

GET/POST/PUT/PATCH/DELETE api/2/assets/:id

Status: Implemented, needs DjangoObjectPermissions configuration.

Replaces:

api/1/?operation=get_asset_info
api/1/rest/assetlocations/:id
api/1/rest/asset/:id

Access permissions:

• Anonymous: None.
• Authenticated: GET/POST. PUT/PATCH/DELETE for objects owned by user.
• Admin: GET/POST/PUT/PATCH/DELETE.

GET/POST/PATCH/DELETE api/2/assets/:id/tags

Access permissions:

• Anonymous: None
• Authenticated: GET. POST/PUT/PATCH/DELETE for objects owned by user.
• Admin: GET/POST/PUT/PATCH/DELETE.

GET/POST/DELETE api/2/assets/:id/actions/vote/[type]

Replaces:

api/1/?operation=vote_asset

Access permissions:

• Anonymous: None
• Authenticated: GET, POST, DELETE, edit/delete for items owned by user only
• Admin: GET, POST, DELETE

GET/POST/PUT/PATCH/DELETE api/2/tags/:id

New Status: Implemented, needs Serializer work.

Access permissions:

• Anonymous: None
• Authenticated: GET
• Admin: GET, POST, PUT, PATCH, DELETE