- Uniform interface
- Identification of resources
- Manipulation through representations
- Self-descriptive message
- Hypermedia as the engine of application state
- Separation between STATE (what is being done) and STATUS (how well it went)
- Use HTTP methods explicitly
- Expose directory structure-like URLs
- Transfer JSON
- Redundant query parameters (not specified in the API) will be disregarded and won't affect execution of API methods
- All calls to non-existing endpoints (not specified in the document) will cause 404 (Not Found) status code to be returned
- Two or more versions should be supported at the same time
- Every API version contains all methods, not just the changed ones (so some version 1 methods may be identical to version 2 methods)
- Different versions will be accessed through URLs by adding 'version' after <base_url>/api/
- It's highly recommended to use only one API version and not to mix them
- Backchannel messaging system will be versioned in such a way that different API versions will communicate via different ports (as communicated via GET /api/<version>/status)
Camera shall store video (MP4 format) and photo (JPG format) files as media files. These files needs to be uniquely identified by it's id which then should be unique for not just all the files on the camera but also for files across many cameras.
Identifiers used in this API shall consists of two logical parts (although seamlessly blended into one id): UUID and 'path' parts. UUID part will be generated by standard Linux UUID library whereas 'path' part will be generated during one session and shall be used to allow camera to quickly locate media file on the SD card. Every media file shall have UUID part of this identifier stored inside it's container thus uniquely identifying a file. For video files, id will be stored in MP4 (in custom 'TTID' atom) and for image files it will be stored in EXIF container. 'Path' part of file identifier won't be stored in media containers.
Format of a file identifier shall therefore be:
File identifier is made out of following parts:
- UUID part
This part is generated by using standard Linux UUID generator and represented in hexadecimal format.
- 'Path' part
- folder number
Given that folder structure (according to DCIM standard) is made out of 3 numbers + 5 alphanumerics, this field will contain folder number in which this particular file can be found. Example: for folder 101TTCAM content of this field will be '101'.
- session number
Contains order number of sessions of burst or continuous (once it's implemented) modes. Session number is part of a filename and will be exposed in this field as well. Example: for file I0340145.JPG content of this field will be '034'. For video files which don't have session numbers content of this field will be '000'.
- media file type
Describes media file type of a file (video, image, part of continuous photo session, burst session...). First 2 characters are reserved and will be set to 0. The third one is used to indicate media file type in a following way:
- 1 - video
- 2 - image
- 3 - file is part of burst session
- 4 - file is part of continuous photo session
- file number
Auto-incremented file number given to every media file at the time it was recorded. Every time video or image is recorded this counter is incremented by 1. Example: for file IMG_1234.JPG content of this field will be '1234'.
- folder number
Implementation of file identifier is internal to camera software and shall not affect API functionality. Total length of file identified shall be 49 characters.
Datetime values used in the API (for both GET and POST methods) should be passed in one of the formats defined by ISO8601 (this standard defines several possible formats).
Exact format used in this API will be:
For example, these are all valid datetimes:
2012-03-04T12:15:40Z 2012-12-31T05:12:59Z 2015-09-10T23:45:12Z
Please note that ISO8601 uses the 24-hour clock system.