HTTP RestFUL API


This document contains information that is proprietary and confidential to COMPANY_NAME. This document is provided to the recipient with the expressed understanding that the recipient will not divulge its contents to other parties or otherwise misappropriate the information contained herein.

Table of contents

  1. Overview
  2. Data format
  3. Major resources for live transcoding
  4. Major resources for file transcoding
  5. Major resources for recording
  6. Primitive Resources types
  7. API operations
  8. Examples (using Live Task Node API)
  9. Interesting variables for monitoring
  1. Overview

    REST is a style of software architecture that provides a convenient and consistent approach to request and modify data.
    The term REST is short for "Representational State Transfer." In the context of COMPANY_NAME Low Level API, it refers to using HTTP verbs to retrieve and modify the configuration of a COMPANY_NAME device.
    A client ask the device to perform a particular action (such as creating, retrieving, updating, or deleting a configuration item), and the device performs the action and sends a response.
    In COMPANY_NAME RESTful APIs, the client specifies an action using an HTTP verb such as POST, GET, PUT and DELETE. It specifies a resource by a globally-unique URI of the following form:

  2. Data format

    The data format used by the Low Level API is JSON.
    JSON (JavaScript Object Notation) is a common, language-independent data format that provides a simple text representation of arbitrary data structures. For more information, see json.org.
  3. Major resources for live transcoding

    1. Live task node

      Base URI Description
      http://[IP_ADDRESS]/api/LiveTaskNode The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/LiveTaskNode/State A structure containing the common configuration shared by all tasks
      http://[IP_ADDRESS]/api/LiveTaskNode/Tasks A map of all tasks present within a specific transcoder.
    2. Live manager

      Base URI Description
      http://[IP_ADDRESS]/api/LiveManager/TemplateManager The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/LiveManager/TemplateManager/DeviceCluster A structure containing the list of devices used by the manager to deploy the tasks
      http://[IP_ADDRESS]/api/LiveManager/TemplateManager/MaskMap A map of all presets as defined by the user
      http://[IP_ADDRESS]/api/LiveManager/TemplateManager/PartitionMap A map of all services as defined by the user
  4. Major resources for file transcoding

    1. File task node

      Base URI Description
      http://[IP_ADDRESS]/api/FileTaskNode The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/FileTaskNode/State A structure containing the common configuration shared by all tasks
      http://[IP_ADDRESS]/api/FileTaskNode/Tasks A map of all tasks present within a specific transcoder.
    2. File manager

      Base URI Description
      http://[IP_ADDRESS]/api/FileManager The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/FileManager/TaskManager/TaskModels A map of all task models that can be pushed
      http://[IP_ADDRESS]/api/FileManager/TaskManager/TaskModels/{model_id}/_state_/Settings The settings of the tasks that can be pushed in the model {model_id}
      http://[IP_ADDRESS]/api/FileManager/TaskManager/TaskModels/{model_id}/_state_/Tasks A map of tasks previously pushed for the model {model_id}
      http://[IP_ADDRESS]/api/FileManager/TaskManager/Assets A map of all the assets that have been created by the tasks that have ended
      http://[IP_ADDRESS]/api/FileManager/TaskManager/Nodes A structure containing the list of devices used by the manager to deploy the tasks
      http://[IP_ADDRESS]/api/FileManager/WatchFolderManager A structure containing the configuration of the watch folders
  5. Major resources for recording

    1. Recording task node

      Base URI Description
      http://[IP_ADDRESS]/api/CatchupNode The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/CatchupNode/State A structure containing the common configuration shared by all tasks
      http://[IP_ADDRESS]/api/CatchupNode/Tasks A map of all tasks present within a specific transcoder.
    2. Recording manager

      Base URI Description
      http://[IP_ADDRESS]/api/CatchupManager The root structure containing the whole configuration tree.
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/Masks A map of all presets as defined by the user
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/TaskModels A map of all task models that can be pushed
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/TaskModels/{model_id}/_state_/Settings The settings of the tasks that can be pushed in the model {model_id}
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/TaskModels/{model_id}/_state_/Tasks A map of tasks previously pushed for the model {model_id}
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/Assets A map of all the assets that have been created by the tasks that have ended
      http://[IP_ADDRESS]/api/CatchupManager/TaskManager/Nodes A structure containing the list of devices used by the manager to deploy the tasks
  6. API operations

    Different methods can be invoked on each element (resource) of the configuration tree.
    Operation Description Rest HTTP mappings Query String
    get Get a specific resource. HTTP GET on a resource URI
    load Load a specific resource, ignoring errors. HTTP POST on a resource URI
    insert Insert an element to a specific resource. HTTP POST on a resource URI ?insert
    delete Delete an element of a specific resource. HTTP DELETE on a resource URI
    set Set a specific resource, returning on first error. HTTP POST on a resource URI ?set
    desc Return the description of the resource. HTTP GET on a resource URI ?desc
    elements The number of elements that conform the map's content. HTTP GET on a resource URI ?elements
    size The number of elements in the container. HTTP GET on a resource URI ?size
    call Perform a call on the function located at this URI. HTTP POST on a resource URI ?call
    clear Clear the resource. HTTP POST on a resource URI ?clear


    The table below shows which methods are supported by each resource type :
    Resource type get load set desc size elements call clear insert delete
    Int32 X X X X
    Int64 X X X X
    string X X X X
    bool X X X X
    struct X X X X
    vector X X X X X
    map X X X X X X X
    function X X
    file X X X X X
    enum X X X X
  7. Examples (using the Live Task Node)

    1. GET operation

      • Get task status

        HTTP GET command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Activation/_value_/ACTIVATED/State/_value_/LIVE_CHANNEL_TASK/Status/ExtendedState (where X is task index)
        Returned value Description
        STARTING Task has received a play order
        WAITING_FOR_DATA Task is waiting for intput data to process
        CODING Tasl is processing data
        STOPPING Task has received a stop order
        WAITING_FOR_PARSE_TS Task is waiting for TS source to be parsed
        NO_OUTPUT_SERVER_CONNECTION Task is waiting for publication server
        FINALIZING Task is finalizing
        STARTING_ERROR Task can't start
        CODING_ERROR Error while processing data
      • Get device CPU load

        HTTP GET command :
        URI : http://[IP_ADDRESS]/objects/device/System/CpuLoad

        If the request succeeds, the server responds with a 200 OK HTTP status code and returns CPU load value.
      • Save task settings

        HTTP GET command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_ (where X is task index)

        Returns task JSON structure.
    2. ELEMENTS operation

      • Get tasks indexes

        HTTP GET command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks?elements

        Returns tasks indexes
        [
            1,
            4,
            5
        ]
        
    3. SIZE operation

      • Get number of H.264 video profiles

        HTTP GET command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Config/Video/EnableVideoProcessing/_value_/true/Codec/_value_/H_264/Streams?size (where X is task index)

        Returns number of video profiles
    4. LOAD operation

      • Change TS input settings

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Config/Input/InputMode/_value_/IP/Udp/UdpSources/Sources/Y/Source/_value_/OtherSource/Type/_value_/Network (where X is task number, and Y is source index)

        Parameters :
        • "Adapter" : Network adapter index
        • "IpAddress" : TS input IP address
        • "Port" : TS input UDP port
        {
           "Adapter" : 3,
           "EnableSsm" : {
              "_type_" : "false",
              "_value_" : {
                 "false" : {}
              }
           },
           "IpAddress" : "226.0.8.8",
           "Port" : 5009
        }
        
      • Change H.264 video bitrate

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Config/Video/EnableVideoProcessing/_value_/true/Codec/_value_/H_264/Streams/Y/CodecSpecific/Bitrate (where X is task index and Y video profile index)

        Parameter : videoBitrateInKbps

      • Load task settings

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_ (where X is task index)

        Parameter : Task JSON structure.
    5. SET operation

      • Start a task

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Activation/_type_?set (where X is task index)
        Parameter : "ACTIVATED"
      • Stop a task

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X/_state_/Activation/_type_?set (where X is task index)
        Parameter : "DEACTIVATED"
    6. INSERT operation

      • Create a new task

        HTTP POST command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks?insert
        Parameter : "{}"
    7. DESC operation

      • Get description of "Get device event logs" function

        HTTP GET command :
        URI : http://[IP_ADDRESS]/objects/device/Traps/RetrieveFormattedTraps?desc

        Returns description of the function :
        • Number of parameters
        • Type of parameters
        • Possible value of each parameter
    8. CALL operation

      • Get device event logs

        HTTP POST command :
        URI : http://[IP_ADDRESS]/objects/device/Traps/RetrieveFormattedTraps?call

        Parameters :
        Key Type Description
        "First" int32 First event index
        "Last" int32 Last event index

        Eg : JSON parameters to get 50-100 event logs range : { "First" : 50, "Last" : 100 }
        Eg : JSON parameters to get last event log: { "First" : -1, "Last" : -1 }
      • Create a VLAN tag

        HTTP POST command :
        URI : http://[IP_ADDRESS]/objects/device/Network/TeamingVlan/AddVirtualAdapter?call

        Parameters :
        Key Type Description
        "TeamMode" int32 Team mode (0 = no Team)
        "VlanTag" int32 VLAN tag number
        "PhysicalAdapters" vector Physical adapter number

        Eg : JSON parameters to add VLAN tag 746 to ethernet adapter #3
        {
            "TeamMode": 0 ,
            "VlanTag":746 ,
            "PhysicalAdapters":[3]
        }
        
    9. DELETE operation

      • Delete a task

        HTTP DELETE command :
        URI : http://[IP_ADDRESS]/api/LiveTaskNode/Tasks/X (where X is task index)
  8. Interesting variables for monitoring