Difference between revisions of "API Upload Recording"

From IVS Wiki
Jump to: navigation, search
(→‎Invalid JSON Body Request payload)
 
(17 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
This API is a two-part request that creates a video record and then uploads a video file to the specified record.
+
{{Aside - Helpful | content = This API is a two-part request that creates a video record and then uploads a video file to the specified record.
 +
# [[#Create Upload Record|Create Upload Record]]
 +
# [[#Upload Video to Record|Upload Video to Record]]
 +
}}
  
−
=1) Create Upload Record=
+
=Create Upload Record=
 
===Request URL===
 
===Request URL===
 
<pre>http://valt.example.com/api/v3/records/create-upload</pre>
 
<pre>http://valt.example.com/api/v3/records/create-upload</pre>
Line 46: Line 49:
 
The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon.
 
The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon.
 
{|class="wikitable"
 
{|class="wikitable"
−
!colspan="3"|data
+
!colspan="3"|Data
 +
!colspan="1"|Required
 
|-
 
|-
 
|colspan="2"|'''name'''
 
|colspan="2"|'''name'''
 
|Recording Name
 
|Recording Name
 +
|Yes
 
|-
 
|-
 
|colspan="2"|'''template'''
 
|colspan="2"|'''template'''
 
|Array of additional information template fields.
 
|Array of additional information template fields.
 +
|No
 
|-
 
|-
 
|colspan="2"|'''share'''
 
|colspan="2"|'''share'''
 
|
 
|
 +
|No
 
|-
 
|-
 
|
 
|
Line 68: Line 75:
  
 
==Response==
 
==Response==
−
===HTTP Code===
+
===HTTP Codes===
 
{|class="wikitable"
 
{|class="wikitable"
 
!Code
 
!Code
Line 80: Line 87:
 
|-
 
|-
 
|500
 
|500
−
|Internal Server Error
+
|Invalid request payload
 
|}
 
|}
−
 
  
 
===JSON Body===
 
===JSON Body===
Line 160: Line 166:
 
</nowiki>
 
</nowiki>
  
−
=2) Upload Video to Record=
+
 
−
===Resource URL===
+
 
 +
=Upload Video to Record=
 +
===Request URL===
 
<pre>http://valt.example.com/api/v3/records/{recordID}/videos/{videoID}</pre>
 
<pre>http://valt.example.com/api/v3/records/{recordID}/videos/{videoID}</pre>
  
Line 173: Line 181:
 
|-
 
|-
 
|'''Authentication Required'''
 
|'''Authentication Required'''
−
|Yes
+
|Yes (access token as a query parameter)
 
|}
 
|}
 +
''Authentication is performed with an access token obtained from the [[API Authentication]] request.''
  
−
===Parameters===
+
 
 +
==Request Parameters==
 +
===Path Parameters===
 
{|class="wikitable"
 
{|class="wikitable"
−
|+Headers
+
!Name
−
!colspan="2"|data
+
!Type
 +
!Description
 
|-
 
|-
−
|colspan="2"|'''content-type'''
+
|'''recordID'''
−
|multipart/form-data
+
|string
 +
|ID of the record to upload to
 
|-
 
|-
−
|colspan="2"|'''content-range'''
+
|'''videoID'''
−
|bytes 0-316620/316620
+
|string
 +
|ID of the video to upload to
 
|}
 
|}
  
 +
===Query Parameters===
 
{|class="wikitable"
 
{|class="wikitable"
−
|+JSON Response
+
!Name
−
!colspan="3"|data
+
!Type
 +
!Description
 
|-
 
|-
−
|colspan="2"|'''name'''
+
|'''access_token'''
−
|Recording Name
+
|string
 +
|Token used for authentication. Must be appended to the request URL.
 +
|}
 +
 
 +
===Headers===
 +
{|class="wikitable"
 +
!Name
 +
!Value
 
|-
 
|-
−
|colspan="2"|'''template'''
+
|colspan="1"|'''content-type'''
−
|Array of additional information template fields.
+
|multipart/form-data
 
|-
 
|-
−
|colspan="2"|'''share'''
+
|colspan="1"|'''content-range'''
−
|
+
|bytes 0-316620/316620
 +
|}
 +
 
 +
===Body===
 +
The Body must be multipart/form-data and include the video file
 +
{|class="wikitable"
 +
!colspan="2"|Data
 +
!colspan="1"|Required
 
|-
 
|-
−
|
+
|colspan="1"|'''file'''
−
|'''groups'''
+
|Video File to upload
−
|Array of group IDs the video is shared with in addition to default video permissions.
+
|Yes
−
|-
 
−
|
 
−
|'''users'''
 
−
|Array of user IDs the video is shared with in addition to default video permissions.
 
 
|}
 
|}
  
−
===Response===
+
 
 +
==Response==
  
 
{|class="wikitable"
 
{|class="wikitable"
Line 216: Line 243:
 
!Reason
 
!Reason
 
|-
 
|-
−
|200
+
|201
 
|Request Successful
 
|Request Successful
 +
|-
 +
|400
 +
|Invalid request payload or headers
 
|-
 
|-
 
|401
 
|401
Line 223: Line 253:
 
|-
 
|-
 
|500
 
|500
−
|Internal Server Error
+
|Invalid request payload
−
|}
 
−
 
 
−
{|class="wikitable"
 
−
|+JSON Response
 
−
!colspan="2"|data
 
−
|-
 
−
|'''url'''
 
−
|Download URL
 
 
|}
 
|}
  
Line 248: Line 270:
  
 
===Successful Response===
 
===Successful Response===
−
Sample response is shown with line breaks to make it more readable. Actual responses will not include line breaks.
+
There is no content returned on a successful response.
 +
 
 +
===Failure Responses===
 +
Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.
 +
====Invalid Content-Range header value====
 +
<nowiki>
 +
{
 +
"data":{
 +
"message": "Invalid range data"
 +
},
 +
"code": 400
 +
}
 +
</nowiki>
 +
 
 +
====The name or identifier for the file chunk is missing. This field must have a non-empty value.====
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
"id": "1bc87bea-9412-43f1-9e95-dbad0e60c99a",
+
"data":{
−
"videos":[
+
"message": "The chunk file was not transferred"
−
"198016d2-edf4-4eaa-aa84-1545b07270e2"
+
},
−
]
+
"code": 400
 
}
 
}
 
</nowiki>
 
</nowiki>
  
−
===Failure Responses===
+
====The file to upload is missing====
−
Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.
 
 
  <nowiki>
 
  <nowiki>
 
{
 
{
Line 268: Line 303:
 
</nowiki>
 
</nowiki>
  
 +
====Unauthorized====
 
  <nowiki>
 
  <nowiki>
 
{
 
{

Latest revision as of 13:17, 9 May 2025

🕮This API is a two-part request that creates a video record and then uploads a video file to the specified record.

  1. Create Upload Record
  2. Upload Video to Record

Create Upload Record

Request URL

http://valt.example.com/api/v3/records/create-upload

Resource Information

Method POST
Response Type JSON
Authentication Required Yes (access token as a query parameter)

Authentication is performed with an access token obtained from the API Authentication request.


Request Parameters

Path Parameters

No path parameters are required for this request.

Query Parameters

Name Type Description
access_token string Token used for authentication. Must be appended to the request URL.

Headers

Name Value
Content-Type application/json

Body

The JSON body must be properly formatted. All fields and values should be enclosed in double quotes and separated by a colon.

Data Required
name Recording Name Yes
template Array of additional information template fields. No
share No
groups Array of group IDs the video is shared with in addition to default video permissions.
users Array of user IDs the video is shared with in addition to default video permissions.


Response

HTTP Codes

Code Reason
200 Request Successful
401 Unauthorized
500 Invalid request payload

JSON Body

data
id Record ID
videos Video ID

Examples

Request

https://ivssvdev1.ad.ipivs.com/api/v3/records/create-upload?access_token=2407c9d2cfde75c49e5d356ee9f83422

Example 1

{
    "name": "Upload Recording"
}

Example 2

{
    "name": "Upload Recording",
    "template": {
        "1": "Field Value 1",
        "2": "Field Value 2",
    },
    "share": {
        "users": [1, 2, 3],
        "groups": [4, 5, 6]
    }
}

Successful Response

Sample response is shown with line breaks to make it more readable. Actual responses will not include line breaks. 

{
"id": "1bc87bea-9412-43f1-9e95-dbad0e60c99a",
"videos":[
	"198016d2-edf4-4eaa-aa84-1545b07270e2"
	]
}

Failure Responses

Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.

Invalid request payload

{
"error":{
"code":500,
"message":"Internal Server Error"
}

Unauthorized

{
"error":{
"code":401,
"message":"No API token provided"
}
}


{
"error":{
"code": 401,
"message": "Bad credentials."
}
}


Upload Video to Record

Request URL

http://valt.example.com/api/v3/records/{recordID}/videos/{videoID}

Resource Information

Method POST
Response Type multipart/form-data
Authentication Required Yes (access token as a query parameter)

Authentication is performed with an access token obtained from the API Authentication request.


Request Parameters

Path Parameters

Name Type Description
recordID string ID of the record to upload to
videoID string ID of the video to upload to

Query Parameters

Name Type Description
access_token string Token used for authentication. Must be appended to the request URL.

Headers

Name Value
content-type multipart/form-data
content-range bytes 0-316620/316620

Body

The Body must be multipart/form-data and include the video file

Data Required
file Video File to upload Yes


Response

Code Reason
201 Request Successful
400 Invalid request payload or headers
401 Unauthorized
500 Invalid request payload

Examples

Request

https://ivssvdev1.ad.ipivs.com/api/v3/records/1bc87bea-9412-43f1-9e95-dbad0e60c99a/videos/198016d2-edf4-4eaa-aa84-1545b07270e2?access_token=2407c9d2cfde75c49e5d356ee9f83422

Headers

"Content-Type": "multipart/form-data"
"Content-Range": "bytes 0-316620/316620"

Body

file [File] = {Video File}

Successful Response

There is no content returned on a successful response.

Failure Responses

Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.

Invalid Content-Range header value

{
"data":{
"message": "Invalid range data"
},
"code": 400
}

The name or identifier for the file chunk is missing. This field must have a non-empty value.

{
"data":{
"message": "The chunk file was not transferred"
},
"code": 400
}

The file to upload is missing

{
"error":{
"code":500,
"message":"Internal Server Error"
}

Unauthorized

{
"error":{
"code":401,
"message":"No API token provided"
}
}


{
"error":{
"code": 401,
"message": "Bad credentials."
}
}
Retrieved from "https://ipivs.info/wiki/index.php?title=API_Upload_Recording&oldid=16109"