Difference between revisions of "API Upload Recording"

From IVS Wiki
Jump to: navigation, search
 
(28 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=
−
===Resource 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 14: Line 17:
 
|-
 
|-
 
|'''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.''
 +
 
 +
 
 +
==Request Parameters==
 +
===Path Parameters===
 +
No path parameters are required for this request.
 +
 
 +
===Query Parameters===
 +
{|class="wikitable"
 +
!Name
 +
!Type
 +
!Description
 +
|-
 +
|'''access_token'''
 +
|string
 +
|Token used for authentication. Must be appended to the request URL.
 +
|}
 +
 
 +
===Headers===
 +
{|class="wikitable"
 +
!Name
 +
!Value
 +
|-
 +
|Content-Type
 +
|application/json
 
|}
 
|}
  
−
===Parameters===
+
===Body===
 
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"
−
|+JSON Response
+
!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 42: Line 73:
 
|}
 
|}
  
−
===Response===
 
  
 +
==Response==
 +
===HTTP Codes===
 
{|class="wikitable"
 
{|class="wikitable"
 
!Code
 
!Code
Line 55: Line 87:
 
|-
 
|-
 
|500
 
|500
−
|Internal Server Error
+
|Invalid request payload
 
|}
 
|}
  
 +
===JSON Body===
 
{|class="wikitable"
 
{|class="wikitable"
−
|+JSON Response
 
 
!colspan="2"|data
 
!colspan="2"|data
 
|-
 
|-
−
|'''url'''
+
|'''id'''
−
|Download URL
+
|Record ID
 +
|-
 +
|'''videos'''
 +
|Video ID
 
|}
 
|}
  
 
==Examples==
 
==Examples==
 
===Request===
 
===Request===
−
<pre>https://ivssvdev1.ad.ipivs.com/api/v3/records/download/6ecfe37c-a2e9-4f2d-b56e-847a4e730ed0/d6799d1c-8e0f-4dc6-9483-8f3545fc5ce5?access_token=2407c9d2cfde75c49e5d356ee9f83422</pre>
+
<pre>https://ivssvdev1.ad.ipivs.com/api/v3/records/create-upload?access_token=2407c9d2cfde75c49e5d356ee9f83422</pre>
 +
====Example 1====
 +
<nowiki>
 +
{
 +
    "name": "Upload Recording"
 +
}
 +
</nowiki>
 +
====Example 2====
 +
<nowiki>
 +
{
 +
    "name": "Upload Recording",
 +
    "template": {
 +
        "1": "Field Value 1",
 +
        "2": "Field Value 2",
 +
    },
 +
    "share": {
 +
        "users": [1, 2, 3],
 +
        "groups": [4, 5, 6]
 +
    }
 +
}
 +
</nowiki>
  
 
===Successful Response===
 
===Successful Response===
Line 74: Line 129:
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
"url": "https://ivssvdev1.ad.ipivs.com:8000/distribution/6ecfe37c-a2e9-4f2d-b56e-847a4e730ed0/1_6ecfe37c-a2e9-4f2d-b56e-847a4e730ed0_1.mp4?filename=Just%2Ba%2Broom%2B%2BTW3304.ad.ipivs.com%2B05-06-2025%2B10-18-AM.mp4&access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJQUzUxMiIsImtpZCI6ImJiZGUyNTk0LWMxMWYtNGIwMy1hYmQ4LWVlNDhjZjNmNWU5NiJ9.eyJpYXQiOjE3NDY1NjM0MTYsIm5iZiI6MTc0NjU2MzQxNiwiZXhwIjoxNzQ2NTY1MjE2LCJpc3MiOiJpdnNzdmRldjEuYWQuaXBpdnMuY29tIiwic3ViIjoiaXZzc3ZkZXYxLmFkLmlwaXZzLmNvbSIsImF1ZCI6Iml2c3N2ZGV2MS5hZC5pcGl2cy5jb20ifQ.annktWv-ij6BuSGJiobaQ8Cl2yAoPMlhzD7inX7XIpJ6bOQxi2gQJ_3fJPZkNl7-7F2xqydrLMH_A2VJdV6xot2g1_4oxmoUlEKNs_aBmn34YtXkq2wc0uv-MVooOPO9sXEPqWZH8mJOPVbwf11o2ZBACxXd5h28oVlc_4u2xjSQXXm32CheTM_5eHcrwi6NfO74tii5EGbUit6-O0utb971K0jfjD9i8q-XitwSO1D01IakQIwbNcP2dqV9SQSjHvNeP3EEg6DfPo0Hwxf6mpYqHdtPK3bsRxQdpXJtna37SRr1raTUiBPk-Xs5tgoP3dtRfiYEaclqVyirwDWLIYTOGNPTZmsi2GZRC7wWeqc7aXWQh_-ZWeUNZJlrzv7AK_GO7gRHLCUKMBKqkfzIQPMd4cMRWuwSO3NIxspDbP1IYi01VHQUc7me2AOGsRWv1w_52xlxhZv3NU36dgvwmt9a2UDtump_k6pblCPGqlEI5UxxMzLPpm4wMQfqb0U4i5uDmvWZX9CqdfDzr_tafMjSQFDueGYN_O1hUI5gTyKzLN6ePchIezToZbGPugHxLOeMs2LpPuVclGNJMabA6OlzmoaU75QIe60BNIU07pjd4UKXFVgVEtL5cjoNyUKT5yKTuywC45demGxzenFRMwjBiUSSA2M_NRl35msl2y8"
+
"id": "1bc87bea-9412-43f1-9e95-dbad0e60c99a",
 +
"videos":[
 +
"198016d2-edf4-4eaa-aa84-1545b07270e2"
 +
]
 
}
 
}
 
</nowiki>
 
</nowiki>
Line 80: Line 138:
 
===Failure Responses===
 
===Failure Responses===
 
Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.
 
Sample responses are shown with line breaks to make it more readable. Actual responses will not include line breaks.
 +
====Invalid request payload====
 
  <nowiki>
 
  <nowiki>
 
{
 
{
−
"type": "https://tools.ietf.org/html/rfc2616#section-10",
+
"error":{
−
"title": "An error occurred",
+
"code":500,
−
"status": 404,
+
"message":"Internal Server Error"
−
"detail": "Not Found"
+
}
 +
</nowiki>
 +
 
 +
====Unauthorized====
 +
<nowiki>
 +
{
 +
"error":{
 +
"code":401,
 +
"message":"No API token provided"
 +
}
 +
}
 +
</nowiki>
 +
 
 +
<nowiki>
 +
{
 +
"error":{
 +
"code": 401,
 +
"message": "Bad credentials."
 +
}
 +
}
 +
</nowiki>
 +
 
 +
 
 +
 
 +
=Upload Video to Record=
 +
===Request URL===
 +
<pre>http://valt.example.com/api/v3/records/{recordID}/videos/{videoID}</pre>
 +
 
 +
===Resource Information===
 +
{|class="wikitable"
 +
|'''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===
 +
{|class="wikitable"
 +
!Name
 +
!Type
 +
!Description
 +
|-
 +
|'''recordID'''
 +
|string
 +
|ID of the record to upload to
 +
|-
 +
|'''videoID'''
 +
|string
 +
|ID of the video to upload to
 +
|}
 +
 
 +
===Query Parameters===
 +
{|class="wikitable"
 +
!Name
 +
!Type
 +
!Description
 +
|-
 +
|'''access_token'''
 +
|string
 +
|Token used for authentication. Must be appended to the request URL.
 +
|}
 +
 
 +
===Headers===
 +
{|class="wikitable"
 +
!Name
 +
!Value
 +
|-
 +
|colspan="1"|'''content-type'''
 +
|multipart/form-data
 +
|-
 +
|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'''
 +
|Video File to upload
 +
|Yes
 +
|}
 +
 
 +
 
 +
==Response==
 +
 
 +
{|class="wikitable"
 +
!Code
 +
!Reason
 +
|-
 +
|201
 +
|Request Successful
 +
|-
 +
|400
 +
|Invalid request payload or headers
 +
|-
 +
|401
 +
|Unauthorized
 +
|-
 +
|500
 +
|Invalid request payload
 +
|}
 +
 
 +
==Examples==
 +
===Request===
 +
<pre>https://ivssvdev1.ad.ipivs.com/api/v3/records/1bc87bea-9412-43f1-9e95-dbad0e60c99a/videos/198016d2-edf4-4eaa-aa84-1545b07270e2?access_token=2407c9d2cfde75c49e5d356ee9f83422</pre>
 +
====Headers====
 +
<nowiki>
 +
"Content-Type": "multipart/form-data"
 +
"Content-Range": "bytes 0-316620/316620"
 +
</nowiki>
 +
====Body====
 +
<nowiki>
 +
file [File] = {Video File}
 +
</nowiki>
 +
 
 +
===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====
 +
<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>
 +
{
 +
"data":{
 +
"message": "The chunk file was not transferred"
 +
},
 +
"code": 400
 +
}
 +
</nowiki>
 +
 
 +
====The file to upload is missing====
 +
<nowiki>
 +
{
 +
"error":{
 +
"code":500,
 +
"message":"Internal Server Error"
 
}
 
}
 
</nowiki>
 
</nowiki>
  
 +
====Unauthorized====
 
  <nowiki>
 
  <nowiki>
 
{
 
{
 
"error":{
 
"error":{
 
"code":401,
 
"code":401,
−
"message":"No API key provided"
+
"message":"No API token provided"
 
}
 
}
 
}
 
}

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"