Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Panel
borderColor#3D3D3D
bgColor#F4F4F4
titleColor#3D3D3D
borderWidth0
titleBGColor#3D3D3D
borderStylesolid

ON THIS PAGE

Table of Contents
maxLevel3
indent20px

Use this endpoint to upload files to the network. Webpages are uploaded as a collection of files in an upload session, while

...

all other files are uploaded individually without a session marker.

Calls to the /

...

Sessions/ endpoints require unique Accept and Content-Type header values (outlined below). Failing to include these header values will prompt a code 406 response

...

Upload Workflow

Webpages

These steps outline how to upload a webpage (i.e. an HTML file and associated asset files)

...

  1. The response body includes a token for the webpage-upload session, as well as an upload token for each file that is part of the webpage.

...

from the server. Unlike other BSN REST endpoints, the upload URL contains the "Upload" path before the API version.

Base URL for these endpoints: https://api.brightsignnetwork.com/Upload/2017/01/REST/Sessions

Upload Workflow

Webpages

These steps outline how to upload a webpage (i.e. an HTML file and associated asset files)

  1. The client makes a POST call to the /Sessions/ endpoint with the following Content-Type value: application/vnd.bsn.start.webpage.

...

  1. upload.arguments.201701+json.

...

  1. The POST request body includes information about the HTML file and associated asset files (including the path of each asset file relative to the HTML file).

    1. The response body includes a token for the webpage-upload session, as well as an upload token for each file that is part of the webpage.

  2. The client begins uploading the webpage HTML file by calling PUT on the /

...

  1. Sessions/{

...

  1. SessionToken}/

...

  1. Uploads/{

...

  1. UploadToken}/ endpoint with the following Content-Type value: application/vnd.bsn.

...

  1. start.webpage.asset.upload.arguments.201701+json.

  2. The client

...

Note
titleNote

All files must be specified in the initial POST call to the /sessions/ endpoint (step 1). You cannot use the PUT /sessions/{sessionToken}/ or POST /sessions/{sessionToken}/uploads/ calls to dynamically add or remove files from the webpage-upload session.

Individual Files

These steps outline how to upload a single, independent file (such as a content file or plugin script).

...

  1. uploads the file to the server by calling POST on the /Sessions/{SessionToken}/Uploads/{UploadToken}/chunks/ endpoint. If the file is larger than approximately 256KB, the client will need to make multiple POST calls and use the ?offset URL parameter to segment the file into chunks.

  2. Once the file chunk(s) have been uploaded, the client completes the HTML file upload by calling PUT on the /Sessions/{SessionToken}/Uploads/{UploadToken}/ endpoint with the following Content-Type value: application/vnd.bsn.complete.webpage.asset.upload.arguments.201701+json.

  3. The client repeats steps 2 through 4 for each asset file associated with the HTML file.

  4. Once all files have been uploaded, the client completes the webpage-upload session by calling PUT on the /Sessions/{SessionToken}/ endpoint with the following Content-Type

...

  1. application/vnd.bsn.

...

  1. complete.

...

  1. webpage.upload.arguments.201701+json. The

...

  1. The response body includes an upload token for the file.

...

Note
titleNote

 Unlike other endpoints, the "/None/" directory is case-sensitive and must be capitalized.

/sessions/

GET

Retrieves currently active webpage-upload sessions.

URL Parameters

  • marker: A value specifying which page to retrieve. This value is useful if the isTruncated entry in the response body of the previous GET call indicates that the number of WebpageUploadStatus instances exceeds the pageSize.
  • filter:  An expression for filtering search results.
  • pageSize: The maximum number of WebpageUploadStatus instances that can be contained in the response body

Headers

  • Accept: application/vnd.bsn.webpage.upload.status.pagedlist.201701+json

Response Body

...

  • "unknown"

  • "queued"

  • "started"

  • "uploading"

  • "stopped"

  • "uploaded"

  • "verified"

  • "cancelled"

  • "corrupted"

  • "collected"

  • "terminated"

  • "completed"

...

  • [int] count: The number of chunks with the specified length and state. A zero value is used for the section of the file that has not been uploaded/queued yet.
  • [int] length: The byte length of the chunk(s)
  • [string] state: The upload 6545163 of the chunk(s)

...

POST

Creates a new webpage-upload session for the webpage and its asset files. This operation returns a token for the entire webpage-upload session, as well as a token for each asset-file upload.

Headers

  • Content-Type: application/vnd.bsn.start.webpage.upload.arguments.201701+json
    • -or- application/vnd.bsn.start.webpage.update.arguments.201701+json
  • Accept: application/vnd.bsn.webpage.upload.status.201701+json, application/vnd.bsn.error+json

Request Body

...

  • "Auto"
  • "Text"
  • "Image"
  • "Video"
  • "Audio"
  • "Webpage"
  • "DeviceWebpage"

...

Response Body

...

  1. response body will include the new contentId values of the uploaded HTML and asset files.

All files must be specified in the initial POST call to the /Sessions/ endpoint (step 1). You cannot use the PUT /Sessions/{SessionToken}/ or POST /Sessions/{SessionToken}/Uploads/ calls to dynamically add or remove files from the webpage-upload session.

Individual Files

These steps outline how to upload a single, independent file (such as a content file or plugin script).

  1. The client makes a POST call to the /Sessions/None/Uploads/ endpoint with the following Content-Type value: application/vnd.bsn.start.content.upload.arguments.201701+json. The POST request body includes information about the file.

    1. The response body includes an upload token for the file.

  2. The client uploads the file to the server by calling POST on the /Sessions/None/Uploads/{UploadToken}/chunks/ endpoint. If the file is larger than approximately 256KB, the client will need to make multiple POST calls and use the ?offset URL parameter to segment the file into chunks.

  3. The client completes the upload by calling PUT on the/Sessions/None/Uploads/{UploadToken}/ endpoint with the following Content-Type value: application/vnd.bsn.complete.content.upload.arguments.201701+json.

 Unlike other endpoints, the "/None/" directory is case-sensitive and must be capitalized.

GET  /

Retrieves currently active webpage-upload sessions.

Parameters

marker string

A value specifying which page to retrieve. This value is useful if the isTruncated entry in the response body of the previous GET call indicates that the number of WebpageUploadStatus instances exceeds the pageSize.

filter string

An expression for filtering search results.

pageSize int

The maximum number of WebpageUploadStatus instances that can be contained in the response body

______________________________________________________________

Headers

Accept: application/vnd.bsn.webpage.upload.status.pagedlist.201701+json

______________________________________________________________

Response Bodies

The Paged List Entity (2017/01)

item WebpageUploadStatus[]

An array of WebpageUploadStatus object instances representing active webpage-upload sessions. Each WebpageUploadStatus instance can have the following entries: 

  • name string: The name of the webpage (i.e. the collection of files that make up the webpage)

  • SessionToken string: A unique identifier for the webpage-upload session

  • UploadToken string: A unique identifier for the HTML-file upload session

  • contentId int: A unique identifier for the Content instance associated with the file being uploaded. This value is 0 while the upload session is in-progress.

  • fileName string: The name of the file being uploaded

  • sha1Hashstring: The SHA1 hash value of the file contents

  • state string: The current state of the content upload session. The possible state values are: 

    Anchor
    state
    state
    "unknown""queued""started""uploading""stopped""uploaded""verified""cancelled""corrupted""collected""terminated""completed"

  • startTime string: A UTC timestamp indicating when the content upload session began. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

  • endTime string: A UTC timestamp indicating when the content upload session ended. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

  • lastActivityTime string: A UTC timestamp indicating the last activity relating to the content upload session. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

  • chunks Chunk[]: An array of Chunk object instances representing chunks of the file. Each Chunk instance can have the following entries:

    • count int: The number of chunks with the specified length and state. A zero value is used for the section of the file that has not been uploaded/queued yet.

    • length int: The byte length of the chunk(s)

    • state  string: The Upload Endpoints (2017/01)#state of the chunk(s)

  • assets WebPageAsset[]: An array of WebPageAsset object instances representing asset files that are part of the webpage. The server currently returns a null value for this parameter. 

POST  /

Creates a new webpage-upload session for the webpage and its asset files. This operation returns a token for the entire webpage-upload session, as well as a token for each asset-file upload.

Headers

Content-Type: application/vnd.bsn.start.webpage.upload.arguments.201701+json

-or- application/vnd.bsn.start.webpage.update.arguments.201701+json

Accept: application/vnd.bsn.webpage.upload.status.201701+json, application/vnd.bsn.error+json

______________________________________________________________

Request Body

name  string

The name of the webpage (i.e. the collection of files that make up the webpage)

...

...

fileName string

The name of the HTML file

...

...

mediaType string

The media type, which must be "Webpage" for the HTML file

fileSize int

The size of the HTML file (in bytes)

...

  • [int] count: The order of the chunk in the sequence
  • [int] length: The length (in bytes) of the chunk 
  • [string] state: The upload 6545163 of the chunk. 

...

sha1Hash string

The SHA1 hash value of the file contents

assets  WebPageAsset[]

An array of WebPageAsset object instances representing asset files to upload as part of the webpage. Each WebPageAsset instance can have the following entries:

  • fileName string: The name of the asset file

  • relativePath string: The path of the asset file relative to the HTML file. The path should be formatted as follows: "\\[directoryA]\\[directoryAb]\\[...]".

  • fileSize int: The size of the asset file (in bytes)

  • mediaType  string: The media type of the asset file. "Auto", "Text", "Image", "Video","Audio""Webpage", and "DeviceWebpage" types are accepted.

    Anchor
    type
    type

  • sha1Hash string: The SHA1 hash value of the file contents

______________________________________________________________

Response Body

name string

The name of the webpage (i.e. the collection of files that make up the webpage)

SessionToken string

The identifier for the webpage-upload session

fileName string

The name of the HTML file

UploadToken string

A unique identifier for the HTML-file upload session

contentId int

A unique identifier for the Content instance associated with the file being uploaded. This value is 0 while the upload session is in-progress.

...

fileSize int

...

The size of the

...

file (in bytes)

...

sha1Hash string

The SHA1 hash value of the file contents

...

state string

The current state of the

...

HTML-file upload session. This value defaults to "

...

started"

...

in the POST response.

...

startTime string

A UTC timestamp indicating when the content upload session began.

...

 The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

endTime string

A UTC timestamp indicating when the content upload session ended.

...

 This value

...

is null

...

 when the session is active.

...

lastActivityTime string

A UTC timestamp indicating the last activity relating to the content upload session

...

. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

chunks Chunk[]

An array of Chunk object instances representing chunks of the HTML/asset file. Each Chunk instance can have the following entries:

...

  • count int

...

  • : The

...

  • order of

...

/sessions/{sessionToken}/

GET

assets WebPageAsset[]

An array of WebPageAsset object instances representing asset files to upload as part of the webpage.

GET  /{SessionToken}/ 

Returns the asset-file upload sessions associated with the specifed webpage-upload session.

Headers

Accept: application/vnd.bsn.webpage.upload

...

.status.201701+json

______________________________________________________________

Response Body

...

name string

...

The name of the webpage (i.e. the collection of files that make up the webpage)

...

SessionToken string

...

A unique identifier for the webpage-upload session

...

assets WebPageAsset[]

...

An array of WebPageAsset object instances representing asset files to upload as part of the webpage. Each WebPageAsset instance can have the following entries:

...

  • SessionToken string

...

  • : The identifier for the webpage-upload session.

...

  • fileName string

...

  • : The name of the asset file

...

  • UploadToken string

...

  • : A unique identifier for the asset-file upload session

...

contentId int

...

: A unique identifier for the

...

content instance

...

associated with the

...

file. This value is 0 while the upload session is in-progress.

...

fileSize int

...

: The size of the

...

file (in bytes)

...

sha1Hash string

...

: The SHA1 hash value of the file contents

...

state string

...

: The

...

current Upload Endpoints (2017/01)#state of the file upload session

...

startTime string

...

: A UTC timestamp indicating when the content upload session began. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

endTime string

...

: A UTC timestamp indicating when the content upload session ended. This value is null when the session is active.

...

lastActivityTime string

...

: A UTC timestamp indicating the last activity relating to the content upload session. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

chunks Chunk[]

...

: An array of Chunk object instances representing chunks of the HTML/asset file.

...

  • [int] count: The number of chunks with the specified length and state. A zero value is used for the section of the file that has not been uploaded/queued yet.
  • [int] length: The byte length of the chunk(s)
  • [string] state: The upload 6545163 of the chunk(s)

...

The server currently returns null for this parameter.

PUT  /{SessionToken}/ 

Completes a webpage-upload session.

Headers

Content-Type

...

Request Bobdy

...

: application/vnd.bsn.complete.webpage.upload.arguments.201701+json

______________________________________________________________

Request Body

name  string

The name of the webpage (i.e. the collection of files that make up the webpage)

...

fileName string

The name of the HTML file

...

fileSize int

...

The size of the HTML file (in bytes)

...

relativePath string

...

The relative path of the HTML file. The path should be formatted as follows: "\\[directoryA]\\[directoryAb]\\[...]". For files in the same directory as the HTML file (or the HTML file itself), the path is specified as "\\".

...

DELETE  /{SessionToken}/ 

Terminates the specified webpage-upload session. The server returns code 204 on success.

GET  /

...

{

...

SessionToken}/

...

Uploads/

...

 

Returns currently active file uploads that are part of the specified webpage-upload session (including both the HTML file and its asset files). Calling GET on the /

...

Sessions/None/

...

Uploads/ endpoint returns independent file uploads (i.e. uploads that are not part of a webpage-upload session).

...

Parameters

marker

...

string

A value specifying which page to retrieve. This value is useful if the isTruncated entry in the response body of the previous GET call indicates that the number of WebpageUploadStatus instances exceeds the pageSize.

filter

...

string

An expression for filtering search results.

pageSize

...

int

The maximum number of WebpageUploadStatus instances that can be contained in the response body

______________________________________________________________

Headers

Accept: application/vnd.bsn.content.upload

...

Response Body

...

.status.pagedlist.201701+json, application/vnd.bsn.error+json

______________________________________________________________

Response Body

totalItemCount int

The total number of WebpageUploadStatus instances relevant to the query

...

pageSize int

The maximum number of WebpageUploadStatus instances that can be returned in a single response

...

isTruncated bool

...

A flag indicating whether the totalItemCount exceeds the pageSize

...

nextMarker string

...

A value that can be included with a subsequent GET call to return additional results that have been truncated

...

sortExpression string

...

The sort expression specified in the URL

...

filterExpression string

...

The filter expression specified in the URL

...

items ContentUploadStatus[

...

]

...

: An array of Content object instances representing HTML and asset file uploads that are part of the session. Each WebpageUploadStatus instance can have the following entries: 

...

  • SessionToken string

...

  • : The identifier for the webpage-upload session

...

  • . The value will be null for an independent file upload.

  • fileName string: The name of the

...

  • file

...

  • UploadToken string

...

  • : A unique identifier for the file upload session

...

  • contentId int

...

  • : A unique identifier for the Content instance

...

  • associated with the file. This value is 0 while the upload session is in-progress.

...

  • fileSize int

...

  • : The size of

...

  • the file (in bytes)

...

  • sha1Hash string

...

  • : The SHA1 hash value of the file contents

...

  • state string

...

  • : The current 

...

...

  • file upload session

...

  • startTime string

...

  • : A UTC timestamp indicating when the content upload session began. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

  • endTime string

...

  • : A UTC timestamp indicating when the content upload session ended. This value is null when the session is active.

...

  • lastActivityTime string

...

  • : A UTC timestamp indicating the last activity relating to the content upload session. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

  • chunks Chunk[]

...

  • :

...

  • An array of Chunk object instances representing chunks of the HTML/asset file. The server currently returns null for this parameter.

...

POST  /{SessionToken}/Uploads/ 

Begins a new file upload. Calling POST on the /

...

Sessions/None/

...

Uploads/  endpoint begins an independent file upload.

...

GET  /{

...

SessionToken}/

...

Uploads/{

...

UploadToken}/ 

GET

Returns the specified active file upload that is part of the specified webpage-upload session. Calling GET on the /

...

Sessions/None/

...

Uploads/{

...

UploadToken}/ endpoint retrieves an independent file upload (i.e. an upload that is not part of a webpage-

...

Headers

  • Accept: application/vnd.bsn.content.upload.status.201701+json

Response Body

...

upload session).

Headers

Accept: application/vnd.bsn.content.upload.status.201701+json

______________________________________________________________

Response Body

SessionToken string

The identifier for the webpage-upload session. The value will be null for an independent file upload.

...

fileName string

...

The name of the file

...

UploadToken string

...

A unique identifier for the file upload session

...

contentId int

...

A unique identifier for the Content instance

...

associated with the file. This value is 0 while the upload session is in-progress.

...

fileSize int

...

The size of the file (in bytes)

...

sha1Hash string

The SHA1 hash value of the file contents

...

state string

The current Upload Endpoints (2017/01)#state of the file upload session

...

startTime string

A UTC timestamp indicating when the content upload session began. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

endTime string

A UTC timestamp indicating when the content upload session ended. This value is null when the session is active.

...

lastActivityTime string

A UTC timestamp indicating the last activity relating to the content upload session. The date/time is formatted as yyyy-mm-ddThh:mm:ss.sssZ.

...

chunks Chunk[]

...

An array of Chunk object instances representing chunks of the file. Each Chunk instance can have the following entries:

...

  • count int

...

  • : The number of chunks with the specified length and state. A zero value is used for the section of the file that has not been uploaded/queued yet.

...

  • length int

...

  • : The byte length of the chunk(s)

...

  • state  string

...

PUT

  • : The

...

PUT  /{SessionToken}/Uploads/{UploadToken}/ 

Starts, completes, or updates a file upload session (depending on the value of the Content-Type header). Calling PUT on the /

...

Sessions/None/

...

Uploads/{

...

UploadToken}/ endpoint modifies an independent file upload.

Headers

Content-Type:

...

 application/vnd.bsn.content.upload.arguments.201701+

...

json

-or- application/vnd.bsn.start.content.upload.arguments.201701+json

-or- application/vnd.bsn.complete.content.upload.arguments.201701+json

-or- application/vnd.bsn.content.update.arguments.201701+json

-or- application/vnd.bsn.start.content.update.arguments.201701+json

-or- application/vnd.bsn.complete.content.update.arguments.201701+json

-or- application/vnd.bsn.webpage.asset.upload.arguments.201701+json

-or- application/vnd.bsn.start.webpage.asset.upload.arguments.201701+json

-or- application/vnd.bsn.complete.webpage.asset.upload.arguments.201701+json

Accept: application/vnd.bsn.content.upload.status.201701+json, application/vnd.bsn.content.upload.negotiation.status.201701+json,

...

Request Body

...

application/vnd.bsn.error+json

______________________________________________________________

Request Body

fileName string

The name of the file

...

fileSize int

...

The size of the file (in bytes)

...

relativePath string

...

The relative path of the file. The path should be formatted as follows: "\\[directoryA]\\[directoryAb]\\[...]". For files in the same directory as the HTML file (or the HTML file itself), the path is specified as "\\".

...

DELETE  /{SessionToken}/Uploads/{UploadToken}/ 

Terminates the specified upload that is part of the specified webpage-upload session. Calling DELETE on the /

...

Sessions/None/

...

Uploads/{

...

UploadToken}/ endpoint terminates an independent file upload. The server returns code 204 on success.

GET  /

...

{

...

SessionToken}/

...

Uploads/{

...

UploadToken}/

...

Chunks/

...

  

Returns the status of all file chunks that are part of the file specified file upload.

Headers

...

  • Accept: application/vnd.bsn.upload.content.chunk.status.list.201701+json

Response Body

...

Accept: application/vnd.bsn.upload.content.chunk.status.list.201701+json

______________________________________________________________

Response Body

chunks Chunk[]

An array of Chunk object instances representing chunks of the file. Each Chunk instance can have the following entries:

...

  • count int

...

  • : The number of chunks with the specified length and state. A zero value is used for the section of the file that has not been uploaded/queued yet.

...

  • length int

...

  • : The byte length of the chunk(s)

...

  • state string

...

POST

  • : The

...

POST  /{SessionToken}/Uploads/{UploadToken}/Chunks/ 

Appends a file chunk to the file upload, placing it in the queue for assembly. The server returns code 202 upon completion.

File chunks don't have to be uploaded in order, and multiple chunks can be uploaded simultaneously. We

...

recommend a default chunk size of 256KB for multi-chunk files, though this number can be flexible depending on network performance. 

...

Parameter

offset

...

The offset of the file chunk (in bytes) from the beginning of the file.

______________________________________________________________

Headers

Accept: application/vnd.bsn.error+json

Content-Type: application/octet-stream

Content-Length: [fileChunkLength]

______________________________________________________________

Request Body

The request body should contain the file-chunk as binary data.

Endpoints:

Table of Contents
maxLevel2
indent20px
excludeUpload Workflow|Endpoints: