REST API v3¶

Since build 5.3.392 the new REST API v3 is available for users.

Warning

REST API v2 is deprecated. All the new methods and features are added to REST API v3 only.

The automatically generated REST API documentation is available on the official Flashphoner web site: REST API v3

Also, the docs are available in Web Call Server admin interface:

Async REST API¶

Some long term operations initiated by REST API queries may be executed asynchronously: reading a watermark picture file, starting a VOD stream, connection to RTSP IP camera and so one. Such REST methods initiate an asynchronous job:

If the job completes within the wait time, it returns 200 OK with the result in the response body.
If the job continues in the background, it returns 202 Accepted with a job identifier. The result can be retrieved later using /jobs/find method — it will be available in the result field of the Job object.

A job may be in one of the possible states at the moment:

PENDING — Job created, waiting to start
RUNNING — Job is in progress
DONE — Job completed successfully
FAILED — Job failed with an error
CANCELLED — Job cancelled by timeout

Job timeouts configuration¶

A standard Prefer header may be used to set a job timeouts at client side

curl --location 'http://localhost:8081/rest-api/v3/vod/startup' \
     --header 'Content-Type: application/json' \
     --header 'Prefer: respond-async, wait=3, timeout=10' \
     --data '{"uri": "vod-live://sample.mp4", "localStreamName": "test", "loop": true}'

Where:

wait=3 — Sync wait time in seconds. Returns 200 OK if the job finishes within the specified time, otherwise 202 Accepted. Default: 5.
timeout=10 — Max execution time in seconds. If the job does not complete within this time, it is automatically canceled. Default: 60.

The corresponding server side settings are

jobs_max_prefer_wait_time=5
jobs_max_prefer_timeout=60

If the Prefer header value is omitted or exceeds these limits, the server setting value is used