Module Media REST API (v1)#

GET /api/v1/media/medias#

get media list

Query Parameters:

sort_order – sort the returned media list by media_id
run_id – filter the returned media list with this run_id
custom_id – filter the returned media list with this custom_id
storage – filter the returned media list with the storage location it comes from
media_type – filter the returned media list based on the type (video or photo)

Status Codes:

200 OK – the media list – JSON Schema: array(media)
500 Internal Server Error – if there is a server internal error
541 – if media are not yet indexed (retry after indexed event)

Example:

Get default sorted unfiltered media list

GET /api/v1/media/medias

[
  {
    "title": "Sat, 16 Jun 2018 14:15:16 +0100",
    "datetime": "20180616T141516+0100",
    "boot_date": "20180616T141516+0100",
    "flight_date": "20180616T141516+0100",
    "gps": {
      "altitude": 10.4,
      "latitude": 20.0,
      "longitude": 30.0
    },
    "size": 16224854,
    "duration": 5162,
    "media_id": "0000001_1",
    "resources": [
      {
        "format": "MP4",
        "height": 2160,
        "media_id": "0000001_1",
        "datetime": "20180616T141516+0100",
        "resource_id": "0000001_0001_1.MP4",
        "size": 16224854,
        "duration": 5162,
        "type": "VIDEO",
        "path": "Projects/Flight01/0000001_photo_0001.JPG",
        "url": "/data/media/0000001_0001_1.MP4",
        "replay_url": "replay/0000001_0001_1.MP4",
        "width": 3840,
        "video_mode": "Standard"
      }
    ],
    "run_id": "F9A5BFD1CE90DF37669BF11B01932F55",
    "custom_id": "Flight01",
    "type": "VIDEO",
    "video_mode": "Standard"
  },
  {
    "title": "Thu, 18 Jan 2018 17:13:51 +0200",
    "datetime": "20180118T171351+0200",
    "boot_date": "20180118T171351+0200",
    "flight_date": "20180118T171351+0200",
    "gps": {
      "altitude": 500,
      "latitude": 500,
      "longitude": 500
    },
    "size": 6996046,
    "media_id": "0000002_1",
    "resources": [
      {
        "format": "JPG",
        "height": 0,
        "media_id": "0000002_1",
        "datetime": "20180118T171351+0200",
        "resource_id": "0000002_0001_1.JPG",
        "size": 3498023,
        "type": "PHOTO",
        "path": "Projects/Flight02/0000002_photo_0001.JPG",
        "url": "/data/media/0000002_0001_1.JPG",
        "thumbnail": "/data/thumbnails/0000002_0001_1.JPG.JPG",
        "preview": "/data/previews/0000002_0001_1.JPG.JPG",
        "width": 0
      },
      {
        "format": "JPG",
        "height": 0,
        "media_id": "0000002_1",
        "datetime": "20180118T171357+0200",
        "resource_id": "0000002_0002_1.JPG",
        "size": 3498023,
        "type": "PHOTO",
        "path": "Projects/Flight02/0000002_photo_0002.JPG",
        "url": "/data/media/0000002_0002_1.JPG",
        "thumbnail": "/data/thumbnails/0000002_0002_1.JPG.JPG",
        "preview": "/data/previews/0000002_0002_1.JPG.JPG",
        "width": 0
      }
    ],
    "run_id": "00000000000000000000000000000000",
    "custom_id": "Flight02",
    "type": "PHOTO"
  }
]

GET /api/v1/media/medias/(media_id)#

get a media

Parameters:

media_id (string) – unique id of the media to delete

Status Codes:

200 OK – the requested media – JSON Schema: media
400 Bad Request – if the request is incorrect (not GET method for instance)
404 Not Found – if the requested media does not exist
500 Internal Server Error – if there is a server internal error
541 – if media are not yet indexed (retry after indexed event)

Example:

Get the media with id 1234567_1

GET /api/v1/media/medias/1234567_1

{
  "title": "Thu, 18 Jan 2018 17:13:51 +0200",
  "datetime": "20180118T171351+0000",
  "boot_date": "20180118T171351+0000",
  "flight_date": "20180118T171351+0000",
  "gps": {
    "altitude": 45.7,
    "latitude": 5.8,
    "longitude": 42.9
  },
  "size": 6996046,
  "media_id": "1234567_1",
  "resources": [
    {
      "format": "JPG",
      "height": 0,
      "media_id": "1234567_1",
      "datetime": "20180118T171351+0000",
      "resource_id": "1234567_0001_1.JPG",
      "thumbnail": "/data/thumbnails/1234567_0001_1.JPG.JPG",
      "preview": "/data/previews/1234567_0001_1.JPG.JPG",
      "gps": {
        "altitude": 45.7,
        "latitude": 5.8,
        "longitude": 42.9
      },
      "size": 3498023,
      "type": "PHOTO",
      "path": "Projects/Flight02/1234567_0001_1.JPG",
      "url": "/data/media/1234567_0001_1.JPG",
      "width": 0
    },
    {
      "format": "JPG",
      "height": 0,
      "media_id": "1234567_1",
      "datetime": "20180118T171359+0000",
      "resource_id": "1234567_0002_1.JPG",
      "size": 3498023,
      "type": "PHOTO",
      "path": "Projects/Flight02/1234567_0002_1.JPG",
      "url": "/data/media/1234567_0002_1.JPG",
      "width": 0
    }
  ],
  "run_id": "00000000000000000000000000000000",
  "custom_id": "Flight02",
  "type": "PHOTO"
}

DELETE /api/v1/media/medias/(media_id)#

delete a media

Parameters:

media_id (string) – the unique id of the media to delete

Query Parameters:

resources – range of resources “[<resource_uid>][-][resource_uid>]” to delete in a media (limits are also deleted)

Status Codes:

200 OK – no error
400 Bad Request – if the request is incorrect
404 Not Found – if the requested media does not exist
500 Internal Server Error – if there is a server internal error
524 – if the request has reached timeout (the request may or may not success later, use removed event as a fallback)
541 – if media are not yet indexed (retry after indexed event)

Example:

Delete the media with id 1234567_1 and all its resources

DELETE /api/v1/media/medias/1234567_1

Delete the resources 0002 to 0007 from the media with id 1234567_1

DELETE /api/v1/media/medias/1234567_1?resources=1234567_0002.EXT-1234567_0007.EXT

Delete the resources up to 0004 from the media with id 1234567_1

DELETE /api/v1/media/medias/1234567_1?resources=-1234567_0004.EXT

Delete the resources starting from 0003 from the media with id 1234567_1

DELETE /api/v1/media/medias/1234567_1?resources=1234567_0003.EXT-

PUT /api/v1/media/medias/(media_id)#

upload a resource to this media

Parameters:

media_id (string) – the unique id of the media to use

Query Parameters:

storage – storage to store the media. Default is same storage than last resource

Status Codes:

200 OK – no error
400 Bad Request – if the request is incorrect
404 Not Found – if the requested media does not exist
500 Internal Server Error – if there is a server internal error
524 – if the request has reached timeout (the request may or may not success later, use removed event as a fallback)
541 – if media are not yet indexed (retry after indexed event)

Example:

Push a resource with media_id 1234567_1

PUT /api/v1/media/medias/1234567_1

DELETE /api/v1/media/medias#

delete all media

Status Codes:

200 OK – no error
400 Bad Request – if the request is incorrect
500 Internal Server Error – if there is a server internal error
524 – if the request has reached timeout (the request may or may not success later, use removed event as a fallback)
541 – if media are not yet indexed (retry after indexed event)

Example:

Delete all media

DELETE /api/v1/media/medias

DELETE /api/v1/media/resources#

delete all resources matching filters (at least one filter must be set)

Query Parameters:

custom_id – filter the resources to delete with this custom_id
resources – range of resources “[<resource_uid>][-][resource_uid>]” to delete (limits are also deleted)

Status Codes:

200 OK – no error
400 Bad Request – if the request is incorrect
500 Internal Server Error – if there is a server internal error
524 – if the request has reached timeout (the request may or may not success later, use removed event as a fallback)
541 – if media are not yet indexed (retry after indexed event)

Example:

Delete all resources with custom id “CHARLES”

DELETE /api/v1/media/resources?custom_id=CHARLES

Delete the resources 0002 to 0007 from the media with custom id CHARLES

DELETE /api/v1/media/resources?custom_id=CHARLES&resources=1234567_0002_1.EXT-1234567_0007_1.EXT

Delete the resources up to 0004 from the media with id custom CHARLES

DELETE /api/v1/media/resources?custom_id=CHARLES&resources=-1234567_0004_1.EXT

Delete the resources starting from 0003 from the media with custom id CHARLES

DELETE /api/v1/media/resources?custom_id=CHARLES&resources=1234567_0003_1.EXT-

DELETE /api/v1/media/resources/(resource_id)#

delete a resource

Parameters:

resource_id (string) – unique id of the resource to delete

Status Codes:

200 OK – no error
400 Bad Request – if the request is incorrect
404 Not Found – if the requested media does not exist
500 Internal Server Error – if there is a server internal error
524 – if the request has reached timeout (the request may or may not success later, use removed event as a fallback)
541 – if media are not yet indexed (retry after indexed event)

Example:

Delete the resource with id 1234567_0001_1.JPG

DELETE /api/v1/media/resources/1234567_0001_1.JPG

GET /api/v1/media/storages#

get all storages

Status Codes:

200 OK – list of storages – JSON Schema: array(string)
400 Bad Request – if the request is incorrect (not a GET request for instance)

GET (resource_url)#

download a resource

Parameters:

resource_url (string) – relative url of the resource (as returned in the resource object)

Status Codes:

200 OK – content of the resource (in response body) – JSON Schema: array(byte)
400 Bad Request – if the request is incorrect (not a GET request for instance)
404 Not Found – if the requested resource does not exist
500 Internal Server Error – if there is a server internal error

GET /api/v1/media/md5/(resource_id)#

get the md5 of photo resource

Parameters:

resource_id (string) – unique id of the resource to process

Status Codes:

200 OK – the requested md5 – JSON Schema: md5
400 Bad Request – if the request is incorrect (not a GET request for instance)
404 Not Found – if the requested resource does not exist
500 Internal Server Error – if there is a server internal error
501 Not Implemented – if the requested resource is not a photo

Example:

Get the resource with id 1234567_0001_1.JPG

GET /api/v1/media/md5/1234567_0001_1.JPG

{
  "media_id": "1234567_1",
  "resource_id": "1234567_0001_1.JPG",
  "md5": "456cff094ebaadb91d54d5f0a2724bfe"
}

GET (thumbnail_url)#

download the thumbnail of a resource

Parameters:

thumbnail_url (string) – relative url of the thumbnail (as returned in the resource object)

Status Codes:

200 OK – content of the thumbnail (in response body) – JSON Schema: array(byte)
400 Bad Request – if the request is incorrect (not a GET request for instance)
404 Not Found – if the resource does not exist or does not contain the requested thumbnail
500 Internal Server Error – if there is a server internal error

GET (preview_url)#

download the preview of a resource

Parameters:

preview_url (string) – relative url of the preview (as returned in the resource object)

Query Parameters:

resolution – the requested resolution for the preview (<width>x<height>, 1600x1200 if not set)
quality – the requested JPEG quality level for the preview (in the [0:100] range, 90 if not set)

Status Codes:

200 OK – content of the preview (in response body) – JSON Schema: array(byte)
400 Bad Request – if the request is incorrect (not a GET request for instance)
404 Not Found – if the requested resource does not exist
500 Internal Server Error – if there is a server internal error

Example:

Get the preview of a resource in default resolution 1600x1200

GET <preview_url>

Get the preview of a resource in resolution 1280x720

GET <preview_url>?resolution=1280x720

Get the preview of a resource with a quality factor of 50

GET <preview_url>?quality=50

Get the preview of a resource in resolution 1920x1080 and quality factor of 99

GET <preview_url>?resolution=1920x1080&quality=99

GET (signature_url)#

download the signature of a resource

Parameters:

signature_url (string) – relative url of the signature (as returned in the resource object)

Status Codes:

200 OK – content of the signature (in response body) – JSON Schema: array(byte)
400 Bad Request – if the request is incorrect (not a GET request for instance)
404 Not Found – if the resource does not contain the requested signature
500 Internal Server Error – if there is a server internal error

GET /api/v1/media/indexing_state#

get the current state of the media indexing

Status Codes:

200 OK – the current indexing state – JSON Schema: indexing_state
400 Bad Request – if the request is incorrect (not a GET request for instance)

Module Media Websocket events (v1)#

Endpoint:

GET /api/v1/media/notifications#

Request Headers:

Connection – Upgrade
Upgrade – websocket

Events:

media_created

media_removed

all_media_removed

resource_created

resource_removed

indexing_state_changed

Module Media JSON Schema (v1)#

media_created#

type	object
properties
name	string
data	media_created_event_data

media_removed#

type	object
properties
name	string
data	media_removed_event_data

all_media_removed#

type	object
properties
name	string

resource_created#

type	object
properties
name	string
data	resource_created_event_data

resource_removed#

type	object
properties
name	string
data	resource_removed_event_data

indexing_state_changed#

type	object
properties
name	string
data	indexing_state_changed_event_data

sort_order#

type	string
oneOf	ascending order
	const	asc
	descending order
	const	desc

md5#

type	object
properties
media_id	string
resource_id	string
md5	string

indexing_state#

type	string
oneOf	media are not indexed and no indexing is in progress (media requests will result in 541 error)
	const	NOT_INDEXED
	media indexing is in progress (media requests will result in 541 error)
	const	INDEXING
	media are indexed (media requests are possible)
	const	INDEXED

media#

type	object
properties
media_id	string
type	media_type
title	string
datetime	string
boot_date	string
flight_date	string
size	integer
duration	integer
run_id	string
custom_id	string
thumbnail	string
gps	gps
photo_mode	photo_mode
panorama_type	panorama_type
expected_count	integer
replay_url	string
resources	type	array
	items	resource
thermal	boolean
video_mode	string

gps#

type	object
properties
latitude	double
longitude	double
altitude	double

resource#

type	object
properties
media_id	string
resource_id	string
type	resource_type
path	string
format	resource_format
datetime	string
size	integer
duration	integer
url	string
thumbnail	string
signature	string
gps	gps
width	integer
height	integer
replay_url	string
thermal	boolean
md5	string
video_mode	string
storage	string

media_type#

type	string
oneOf	the media contains photo resources
	const	PHOTO
	the media contains video resources
	const	VIDEO

resource_type#

type	string
oneOf	the resource is a photo
	const	PHOTO
	the resource is a video
	const	VIDEO

resource_format#

type	string
oneOf	the resource is a dng photo
	const	DNG
	the resource is a jpg photo
	const	JPG
	the resource is an mp4 video
	const	MP4

photo_mode#

type	string
oneOf	single shot mode
	const	SINGLE
	bracketing mode (take a burst of 3 or 5 frames with a different exposure)
	const	BRACKETING
	burst mode (take burst of frames)
	const	BURST
	panorama mode (take successive set of photos from one hovering point while rotating)
	const	PANORAMA
	timelapse mode (take successive set of photos at a specific frequency)
	const	TIMELAPSE
	gpslapse mode (take successive set of photos at a specific distance from one another)
	const	GPSLAPSE

panorama_type#

type	string
oneOf	180 degrees on the horizontal plane
	const	HORIZONTAL_180
	180 degrees on the vertical plane
	const	VERTICAL_180
	360 degrees on the horizontal and vertical planes
	const	SPHERICAL

media_created_event_data#

type	object
properties
media	media

media_removed_event_data#

type	object
properties
media_id	string

indexing_state_changed_event_data#

type	object
properties
old_state	indexing_state
new_state	indexing_state

resource_created_event_data#

type	object
properties
resource	resource

resource_removed_event_data#

type	object
properties
resource_id	string

Module Media (v1)#

REST Requests:#

Websockets:#

Module Media REST API (v1)#

Module Media Websocket events (v1)#

Module Media JSON Schema (v1)#

media_created#

media_removed#

all_media_removed#

resource_created#

resource_removed#

indexing_state_changed#

sort_order#

md5#

indexing_state#

media#

gps#

resource#

media_type#

resource_type#

resource_format#

photo_mode#

panorama_type#

media_created_event_data#

media_removed_event_data#

indexing_state_changed_event_data#

resource_created_event_data#

resource_removed_event_data#