Difference between revisions of "Onvif Device Reference Design/Getting Started/REST API"

From RidgeRun Developer Connection
Jump to: navigation, search
(→‎Supported requests)
m
 
(27 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
<noinclude>
 
<noinclude>
−
{{Onvif_Device_Reference_Design/Head|previous=Getting Started/Evaluating the Project|next=Getting Started/Purchasing a License|keywords=}}
+
{{Onvif_Device_Reference_Design/Head|previous=Getting Started/Evaluating the Project using Docker|next=Getting Started/Purchasing a License|metakeywords=}}
 
</noinclude>
 
</noinclude>
  
 +
{{DISPLAYTITLE:ONVIF Device Reference Design - REST API|noerror}}
  
−
= Introduction =
+
== Introduction ==
−
This project provides a REST API that can be used to access different capabilities of the device. This allows you to modify, for example, configurations, sources and encoders by using REST requests.
+
This project provides a REST API that can be used to access different capabilities of the device. This allows you to modify, for example, configurations, sources, and encoders by using REST requests.
−
= Important considerations =
+
== Important considerations ==
 
* We are using Flask as an example of implementations for testing purposes, for commercial implementations, or an implementation exposed to the public, you need to use a server suited for deployment.
 
* We are using Flask as an example of implementations for testing purposes, for commercial implementations, or an implementation exposed to the public, you need to use a server suited for deployment.
 
* The OpenSSL keys used are an example of an OpenSSL implementation, and they should be treated like that, for a final implementation we recommend generating or creating your own keys.
 
* The OpenSSL keys used are an example of an OpenSSL implementation, and they should be treated like that, for a final implementation we recommend generating or creating your own keys.
  
−
= Supported requests =
+
== Supported requests ==
  
−
As previously mentiones, this project offers a REST API, these are the current supported requests.
+
As previously mentioned, this project offers a REST API, these are the current supported requests.
  
−
==Get Methods==
+
===Resources===
  
−
===Link point: /device-information ===
+
====/device-information ====
 
Gets the information of the device.
 
Gets the information of the device.
−
Type of structure: JSON
+
Content type: JSON
  
−
Values of the JSON:
+
{| class="wikitable"
−
# '''firmware''': firmware version of the device.
+
!colspan="3"|GET
−
## ''type'': string
+
|-
−
# '''serial_number''': serial number of the device.
+
|'''Field name'''
−
## ''type'': string
+
|'''Type'''
−
# '''hardware_id''': hardware ID of the device.
+
|'''Description'''
−
## ''type'': string
+
|-
−
# '''model''': model of the device.
+
|firmware
−
## ''type'': string
+
|string
−
# '''manufacturer''': manufacturer of the device.
+
|Device Firmware Version
−
## ''type'': string
+
|-
 +
|serial_number
 +
|string
 +
|Device Serial Number
 +
|-
 +
|hardware_id
 +
|string
 +
|Device Hardware ID
 +
|-
 +
|model
 +
|string
 +
|Device Model
 +
|-
 +
|manufacturer
 +
|string
 +
|Device Manufacturer
 +
|}
  
 
Example:
 
Example:
 +
 +
<pre>
 +
GET /device-information
 +
</pre>
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 45: Line 66:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Link point: /sources/video ===
+
====/sources/video====
  
 
Get the information of all the video sources.
 
Get the information of all the video sources.
 +
Content type: JSON
  
−
Type of structure: JSON
+
{| class="wikitable"
 +
!colspan="3"|GET/PUT
 +
|-
 +
|'''Field name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|-
 +
|name
 +
|string
 +
|Video Source name
 +
|-
 +
|enabled
 +
|int
 +
|1 enabled, 0 disabled
 +
|}
  
−
Values of the JSON:
 
  
−
# '''sources''': list of JSON's that describes all the sources.
+
Examples:
−
## ''type'': list
+
<pre>
−
 
+
GET /sources/video
−
The JSON's structure that is inside the sources list is:
+
</pre>
−
 
+
<pre>
−
# '''name''': name of the video element.
+
PUT /sources/video
−
## ''type'': string
+
</pre>
−
 
 
−
# '''enabled''': 1 for enabled, 0 for disabled.
 
−
## ''type'': int
 
−
 
 
−
# '''device''': source device from which it is captured.
 
−
## ''type'': string
 
−
 
 
−
Example:
 
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 79: Line 106:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Link point: /encoders/video ===
+
====/encoders/video====
  
 
Get the information of all the video encoders
 
Get the information of all the video encoders
−
Type of structure: JSON
+
Content type: JSON
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''encoders''': list of JSON's that describes all the encoders.
 
−
## ''type'': list
 
−
 
 
−
The JSON's structure that is inside the sources list is:
 
  
−
# '''name''': name of the encoder element.
+
{| class="wikitable"
−
## ''type'': string
+
!colspan="3"|GET/PUT
 +
|-
 +
|'''Field name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|-
 +
|name
 +
|string
 +
|Video Encoder name
 +
|-
 +
|enabled
 +
|int
 +
|1 enabled, 0 disabled
 +
|}
  
−
# '''enabled''': 1 for enabled, 0 for disabled.
+
Examples:
−
## ''type'': int
 
  
−
# '''device''': encoder device that is used in the encoding process.
+
<pre>
−
## ''type'': string
+
GET /encoders/video
−
 
+
</pre>
−
Example:
+
<pre>
 +
PUT /encoders/video
 +
</pre>
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 114: Line 148:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
====/configurations/sources/video====
−
 
 
−
 
 
−
 
 
−
===Link point: /configurations/sources/video ===
 
  
 
Get information of all the video source configurations
 
Get information of all the video source configurations
 +
Content type: JSON
  
−
Type of structure: JSON
+
{| class="wikitable"
−
 
+
!colspan="3"|GET/PUT
−
Values of the JSON:
+
|-
 +
|'''Field name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|-
 +
|c_name
 +
|string
 +
|Video Source Configuration Name
 +
|-
 +
|s_name
 +
|String
 +
|Name of the video source to be used by the configuration
 +
|-
 +
|in_use
 +
|int
 +
|Indicates whether or not the configuration is in use
 +
|-
 +
|action
 +
|string
 +
|Action on the configuration. Possible values: create, delete
 +
|}
  
−
# '''configurations''': list of JSON's that describes all the encoders.
+
Examples:
−
## ''type'': list
 
−
 
 
−
The JSON's structure that is inside the sources list is:
 
−
 
 
−
# '''c_name''': configurations name.
 
−
## ''type'': string
 
−
 
 
−
# '''s_name''': associated source name.
 
−
## ''type'': string
 
−
 
 
−
# '''in_use''': 1 if it is in use, 0 in other case.
 
−
## ''type'': int
 
−
 
 
−
 
 
−
Example:
 
  
 +
<pre>
 +
GET /configurations/sources/video
 +
</pre>
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
  
Line 165: Line 204:
  
 
         }
 
         }
−
 
−
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
<pre>
 +
PUT /configurations/sources/video
 +
</pre>
 +
<syntaxhighlight lang="json">
  
−
===Link point: /reboot ===
+
{
−
 
+
  "c_name": "configuration1",
−
Reboots the system
+
  "s_name":"video1",
−
 
+
  "action": "create"
−
Type of structure: JSON
+
}
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''status''': list of JSON's has the status information.
 
−
## ''type'': list
 
−
 
 
−
The JSON's structure that is inside the status is:
 
−
 
 
−
# '''code''': code of the response
 
−
## ''type'': int
 
−
 
 
−
# '''description''': statys code description.
 
−
## ''type'': string
 
−
 
 
−
Example:
 
−
 
 
−
<syntaxhighlight lang="json">
 
−
{"status": {
 
−
              "code": 200,
 
−
              "description": "Device has been reboot successfully"
 
−
            }}
 
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
==Put Methods==
+
====/configurations/encoders/video====
  
−
===Link point: /sources/video ===
+
Get information of all the video source configurations
−
 
+
Content type: JSON
−
Enables or disables video sources. All video sources cannot be disabled.
 
−
 
 
−
Type of structure: JSON
 
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''sources''': list of JSON's that describes all the sources.
 
−
## ''type'': list
 
−
 
 
−
The JSON's structure that is inside the sources list is:
 
−
 
 
−
# '''name''': name of the source element.
 
−
## ''type'': string
 
−
 
 
−
# '''enabled''': 1 for enabled, 0 for disabled.
 
−
## ''type'': int
 
  
 +
{| class="wikitable"
 +
!colspan="3"|GET/PUT
 +
|-
 +
|'''Field name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|-
 +
|c_name
 +
|string
 +
|Video Encoder Configuration Name
 +
|-
 +
|e_name
 +
|String
 +
|Name of the video encoder to be used by the configuration
 +
|-
 +
|in_use
 +
|int
 +
|Indicates whether or not the configuration is in use
 +
|-
 +
|action
 +
|string
 +
|Action on the configuration. Possible values: create, delete
 +
|}
  
−
Example:
+
Examples:
  
 +
<pre>
 +
GET /configurations/encoders/video
 +
</pre>
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
−
{"encoders": [
 
−
{"name": "source1", "enabled": 1},
 
  
−
{"name": "source2", "enabled": 0},
+
{
−
 
+
            "configurations": [
−
{"name": "source3", "enabled": 1}
+
                {
−
]}
+
                    "c_name": "configuration1",
 +
                    "e_name":"H264",
 +
                    "in_use": 1
 +
                },
 +
                {
 +
                    "c_name": "configuration2",
 +
                    "e_name":"H265",
 +
                    "in_use": 0
 +
                }
 +
            ]
 +
        }
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Link point: /encoders/video ===
+
<pre>
−
 
+
PUT /configurations/encoders/video
−
Disables or enables video encoders, not all video encoders can be disabled.
+
</pre>
−
 
 
−
Type of structure: JSON
 
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''encoders''': list of JSON's that describes all the encoders.
 
−
## ''type'': list
 
−
 
 
−
The JSON's structure that is inside the sources list is:
 
−
 
 
−
# '''name''': name of the encoder element.
 
−
## ''type'': string
 
−
 
 
−
# '''enabled''': 1 for enabled, 0 for disabled.
 
−
## ''type'': int
 
−
 
 
−
 
 
−
Example:
 
−
 
 
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
−
{"encoders": [
 
−
{"name": "encoder1", "enabled": 1},
 
−
 
−
{"name": "encoder2", "enabled": 0},
 
  
−
{"name": "encoder3", "enabled": 1}
 
−
]}
 
−
</syntaxhighlight>
 
−
 
−
 
−
 
−
 
−
 
−
 
−
===Link point: /configurations/sources/video ===
 
−
 
−
Creates a new video sources configuration. Two configurations with the same name cannot exist.
 
−
 
−
Type of structure: JSON
 
−
 
−
Values of the JSON:
 
−
 
−
# '''c_name''': name of the configuration.
 
−
## ''type'': string
 
−
 
−
# '''s_name''': name of the source.
 
−
## ''type'': string
 
−
 
−
# '''action''':action to operate to the configuration. It has two possible values; create and delete.
 
−
## ''type'': string
 
−
 
−
 
−
Example:
 
−
 
−
<syntaxhighlight lang="json">
 
 
{
 
{
−
  "c_name": name,
+
  "c_name": "configuration1",
−
  "s_name": device,
+
  "e_name":"H264",
−
  "action": "create",
+
  "action": "create"
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 +
====/reboot ====
  
−
===Link point: /configurations/encoders/video ===
+
Reboots the system
−
 
+
Content type: JSON
−
Creates a new video encoders configuration. Two configurations with the same name cannot exist.
 
−
 
 
−
Type of structure: JSON
 
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''c_name''': name of the configuration.
 
−
## ''type'': string
 
−
 
 
−
# '''e_name''': name of the encoder.
 
−
## ''type'': string
 
−
 
 
−
# '''action''':action to operate to the configuration. It has two possible values; create and delete.
 
−
## ''type'': string
 
  
 +
{| class="wikitable"
 +
!colspan="3"|GET
 +
|-
 +
|'''Field name'''
 +
|'''Type'''
 +
|'''Description'''
 +
|-
 +
|code
 +
|int
 +
|Http Error code
 +
|-
 +
|description
 +
|String
 +
|Human readable error description
 +
|}
  
 
Example:
 
Example:
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
−
{
+
{"status": {
−
  "c_name": name,
+
              "code": 200,
−
  "e_name": device,
+
              "description": "Device has been reboot successfully"
−
  "action": "create",
+
            }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Link point: /discovery ===
+
====/discovery ====
  
 
Enables or disables auto-discover functionality.
 
Enables or disables auto-discover functionality.
 +
Content type: JSON
  
−
Type of structure: JSON
+
{| class="wikitable"
−
 
+
!colspan="3"|GET/PUT
−
Values of the JSON:
+
|-
−
 
+
|'''Field name'''
−
# '''enabled''': 1 for enabled, 0 for disabled.
+
|'''Type'''
−
## ''type'': string
+
|'''Description'''
−
 
+
|-
 +
|enabled
 +
|int
 +
|0 Discovery disabled, 1 Discovery enabled
 +
|}
  
 
Example:
 
Example:
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
−
{'enabled': 1}
+
{"enabled": 1}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
  
−
===Link point: /configurations/encoders/video ===
+
====/login ====
−
 
 
  
 +
Logins using the ONVIF user, this returns a bearer token that needs to be used in every request to verify the user.
 +
Content type: JSON
  
−
Type of structure: JSON
+
{| class="wikitable"
−
 
+
!colspan="3"|PUT
−
Values of the JSON:
+
|-
−
 
+
|'''Field name'''
−
# '''c_name''': name of the configuration.
+
|'''Type'''
−
## ''type'': string
+
|'''Description'''
−
 
+
|-
−
# '''e_name''': name of the encoder.
+
|username
−
## ''type'': string
+
|string
−
 
+
|User name
−
# '''action''':action to operate to the configuration. It has two possible values; create and delete.
+
|-
−
## ''type'': string
+
|password
−
 
+
|string
 +
|User password
 +
|}
  
 
Example:
 
Example:
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
−
{
+
{"username": "username",
−
  "c_name": name,
+
"password": "password:
−
  "e_name": device,
 
−
  "action": "create",
 
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
===Link point: /login ===
+
Return value:
−
 
 
−
Logins using the SOAP user, this returns a bearer token that needs to be used in every request to verify the user.
 
−
Type of structure: JSON
 
−
 
 
−
Values of the JSON:
 
−
 
 
−
# '''username''': username.
 
−
## ''type'': string
 
−
 
 
−
# '''username''': password.
 
−
## ''type'': string
 
−
 
 
−
Example:
 
−
 
 
−
<syntaxhighlight lang="json">
 
−
{"username": username,
 
−
"password": password}
 
−
</syntaxhighlight>
 
−
 
 
−
It returns a json like:
 
  
−
# '''sessionToken''': unique string assigned for every logged session.
+
* '''sessionToken''': unique string assigned for every logged session.
−
## ''type'': string
+
** ''type'': string
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 402: Line 375:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
−
 
+
====/validateUser ====
−
 
 
−
===Link point: /validateUser ===
 
  
 
Validates if a token is still usable.
 
Validates if a token is still usable.
 +
Content type: JSON
  
−
Type of structure: JSON
+
{| class="wikitable"
−
 
+
!colspan="3"|PUT
−
Values of the JSON:
+
|-
−
 
+
|'''Field name'''
−
# '''sessionToken''': unique string assigned for every logged session.
+
|'''Type'''
−
## ''type'': string
+
|'''Description'''
−
 
+
|-
−
Example:
+
|sessionToken
−
 
+
|string
−
<syntaxhighlight lang="json">
+
|unique string assigned for every logged session.
−
{"sessionToken": "xsadf8234"}
+
|}
−
</syntaxhighlight>
+
Return value:
−
 
 
−
It returns a json like:
 
  
−
# '''valid''': int that specifies if the session token is valid.
+
* '''valid''': int that specifies if the session token is valid.
−
## ''type'': 1 for valid, 0 for invalid
+
** ''type'': 1 for valid, 0 for invalid
  
 
<syntaxhighlight lang="json">
 
<syntaxhighlight lang="json">
Line 432: Line 402:
  
 
<noinclude>
 
<noinclude>
−
{{Onvif_Device_Reference_Design/Foot|Getting Started/Evaluating the Project|Getting Started/Purchasing a License}}
+
{{Onvif_Device_Reference_Design/Foot|Getting Started/Evaluating the Project using Docker|Getting Started/Purchasing a License}}
 
</noinclude>
 
</noinclude>

Latest revision as of 10:02, 5 March 2023




Previous: Getting Started/Evaluating the Project using Docker Index Next: Getting Started/Purchasing a License
ONVIF Device Reference Design
Onvif Device Reference Design
Project Architecture
Getting Started
Reference Designs
Customizing the Project
Contact Us





Introduction

This project provides a REST API that can be used to access different capabilities of the device. This allows you to modify, for example, configurations, sources, and encoders by using REST requests.

Important considerations

  • We are using Flask as an example of implementations for testing purposes, for commercial implementations, or an implementation exposed to the public, you need to use a server suited for deployment.
  • The OpenSSL keys used are an example of an OpenSSL implementation, and they should be treated like that, for a final implementation we recommend generating or creating your own keys.

Supported requests

As previously mentioned, this project offers a REST API, these are the current supported requests.

Resources

/device-information

Gets the information of the device. Content type: JSON

GET
Field name Type Description
firmware string Device Firmware Version
serial_number string Device Serial Number
hardware_id string Device Hardware ID
model string Device Model
manufacturer string Device Manufacturer

Example: 

GET /device-information

{"firmware": "1.0.0.0",
"serial_number": "123",
"hardware_id": "1",
"model": "model_1",
"manufacturer": "RidgeRun",
}

/sources/video

Get the information of all the video sources. Content type: JSON

GET/PUT
Field name Type Description
name string Video Source name
enabled int 1 enabled, 0 disabled


Examples: 

GET /sources/video

PUT /sources/video

{"sources":[
{"name":"video1","enabled":1},

{"name":"video2","enabled":1},

{"name":"video3","enabled":1}
]}

/encoders/video

Get the information of all the video encoders Content type: JSON

GET/PUT
Field name Type Description
name string Video Encoder name
enabled int 1 enabled, 0 disabled

Examples: 

GET /encoders/video

PUT /encoders/video

{"encoders":[
{"name":"h265","enabled":1},

{"name":"h264","enabled":0},

{"name":"mpeg","enabled":1}
]}

/configurations/sources/video

Get information of all the video source configurations Content type: JSON

GET/PUT
Field name Type Description
c_name string Video Source Configuration Name
s_name String Name of the video source to be used by the configuration
in_use int Indicates whether or not the configuration is in use
action string Action on the configuration. Possible values: create, delete

Examples: 

GET /configurations/sources/video

{
            "configurations": [
                {
                    "c_name": "configuration1",
                    "s_name":"video1",
                    "in_use": 1
                },
                {
                    "c_name": "configuration2",
                    "s_name":"video2",
                    "in_use": 0
                },
                {
                    "c_name": "configuration3",
                    "s_name":"video3",
                    "in_use": 1
                },
            ]

        }

PUT /configurations/sources/video

{
  "c_name": "configuration1",
  "s_name":"video1",
  "action": "create"
}

/configurations/encoders/video

Get information of all the video source configurations Content type: JSON

GET/PUT
Field name Type Description
c_name string Video Encoder Configuration Name
e_name String Name of the video encoder to be used by the configuration
in_use int Indicates whether or not the configuration is in use
action string Action on the configuration. Possible values: create, delete

Examples: 

GET /configurations/encoders/video

{
            "configurations": [
                {
                    "c_name": "configuration1",
                    "e_name":"H264",
                    "in_use": 1
                },
                {
                    "c_name": "configuration2",
                    "e_name":"H265",
                    "in_use": 0
                }
            ]
        }

PUT /configurations/encoders/video

{
  "c_name": "configuration1",
  "e_name":"H264",
  "action": "create"
}

/reboot

Reboots the system Content type: JSON

GET
Field name Type Description
code int Http Error code
description String Human readable error description

Example: 

{"status": {
              "code": 200,
              "description": "Device has been reboot successfully"
            }
}

/discovery

Enables or disables auto-discover functionality. Content type: JSON

GET/PUT
Field name Type Description
enabled int 0 Discovery disabled, 1 Discovery enabled

Example: 

{"enabled": 1}


/login

Logins using the ONVIF user, this returns a bearer token that needs to be used in every request to verify the user. Content type: JSON

PUT
Field name Type Description
username string User name
password string User password

Example: 

{"username": "username",
 "password": "password: 
}

Return value:

  • sessionToken: unique string assigned for every logged session.
    • type: string
{"sessionToken":session_token}

/validateUser

Validates if a token is still usable. Content type: JSON

PUT
Field name Type Description
sessionToken string unique string assigned for every logged session.

Return value:

  • valid: int that specifies if the session token is valid.
    • type: 1 for valid, 0 for invalid
{"valid": 1}



Previous: Getting Started/Evaluating the Project using Docker Index Next: Getting Started/Purchasing a License



Retrieved from "http://developer.ridgerun.com/wiki/index.php?title=Onvif_Device_Reference_Design/Getting_Started/REST_API&oldid=47171"