Table of Contents
  1. /Storage/Content
    1. PUT
      1. Response Parameters
    2. POST
    3. GET
    4. DELETE
  2. Content IDs (Resource names)
  3. Content Types
    1. Prohibited Content-Types
  4. Visibilities
    1. Javascript Library

/Storage/Content

Allows the client to upload, share, update and delete content on the server. The resource accepts GET, PUT, POST and DELETE methods, as well as sub-paths to identify individual content.

PUT

The PUT method is used to upload new content, in the name of the agent, to the server. You need to be logged in to use this method, and the Content-Type HTTP Header must be recognized by the server. If you provide a Content ID (see below), as part of the URL, it must contain a file extension that matches the registered Content-Type, to avoid the possibility content being used to exploit vulnerabilities in clients. You use the X-Visibility HTTP header to control the visibility (see below) of the uploaded content.

The response to a PUT successful request, would be as follows:

JSON
{
	"uploaded": Required(DateTime(PUploaded)),
	"visibility": Required(Str(PVisibility)),
	"etag": Required(Str(PEtag)),
	"url": Required(Str(PUrl))
}
XML
<ContentReference xmlns="https://waher.se/Schema/BrokerAgent.xsd"
                  uploaded=(Required(DateTime(PUploaded)))
                  visibility=(Required(Str(PVisibility)))
                  etag=(Required(Str(PEtag)))
                  url=(Required(Str(PUrl)))/>

Response Parameters

Parameter Description
PUploaded When the content was uploaded, in UTC.
PVisibility Visibility for the content.
PEtag The ETag value for the content.
PUrl URL of uploaded content.

POST

You can also upload new content using the POST method. If using this method, the Content-Type must be Form Data (i.e. encoded using Content-Type: multipart/form-data). The form must contain the following input fields

Field Name Type Description
Content file File being uploaded.
ContentId text Optional Content-ID (see below.)
Visibility text Visibility of content. Should be implemented as a Select, list or Combo-box in a user-interface.

Except through the format of the input, the rules for processing the upload is the same, as for using the PUT command. The response is also the same.

GET

Once content has been uploaded, you receive a URL that can be shared with other users. They can use the GET method to retrieve the content, as long as they can pass the authorization requirements (see Visibilities, below). When retrieving content, you will get a binary copy of the previously uploaded content, with the same Content-Type, as was used when uploading the content.

DELETE

As an uploader of content, you can upload new versions of the content using the PUT and POST methods above. If you choose to, you can also delete it, by using the DELETE method on the URL corresponding to the content.

Content IDs (Resource names)

Content IDs consists of the last part of the URL of the content created. Uploaded content will have the following syntax:

http(s)://DOMAN/Agent/Storage/Content/USERNAME/CONTENT_ID

Here, DOMAIN is replaced by the domain name of the broker, USERNAME is replaced by the user-name of the agent uploading the content, and CONTENT_ID is the ID of the content that has been uploaded. It must end using a file-extension that matches the Content-Type of the content. It can include the path / separator, allowing the agent to create a resource tree structure of uploaded content. When performing a PUT operation, the full URL must be used. When performing a POST operation, only the CONTENT_ID portion will be used.

If a Content-ID is provided when uploading the file, it will be used (if approved), and the URL will reflect this Content-ID. If one is not provided, one will be generated, based on the ETag of the uploaded content.

Content Types

Content being uploaded must have a Content-Type that is recognized by the Neuron®. The content must also use a file extenstion that matches the registered Content-Type. This to prevent the user from uploading files that can create vulnerabilities in clients.

To learn what Content-Types are supported by your broker, type the following script in a script Prompt on the server:

InternetContent.CanDecodeContentTypes T

On this server, this list includes:

Prohibited Content-Types

The following types of content cannot be uploaded, for security reasons, as these are processed by the server:

Visibilities

The visibility enumeration contains the possible values the visibility parameter can have. The following table lists possible values and their meanings:

Visibility Description
Public Access to content is public, and content can be retrieved anonymously.
Presence Access to content is restricted to contacts in the uploaders roster, with an approved presence subscription.
Private Access to content can only be made by the uploader.

Javascript Library

Use the following asynchronous method in the Javascript Library, to upload content using the POST method. Content here points to the file input.

var Response = await AgentAPI.Storage.Upload(ContentFile,ContentId,Visibility);
Test





Request Payload:

Response Payload: