Files
Manages a collection of files.
This root REST resource allows the download, upload and removal of resource files in the KnowledgeStore.
File download is performed via GET requests and supports caching and conditional requests based on file modification date and ETag (MD5 hash of file content); file metadata is taken from the ks:storedAs resource property and is returned via standard HTTP headers.
File upload can be performed via PUT requests whose body is the file content, or via POST request with multipart/form-data body; the PUT approach should be preferred in client libraries supporting the PUT operation, whereas the POST approach can be used when uploading from an HTML form using a browser. File metadata can be supplied either via standard HTTP headers or via custom X-KS-Content-Meta key-value headers.
File deletion can be performed either with DELETE requests or via POST requests lacking a file form parameter.
The following resources are applicable:
/files
Mount Point: /rest/files
The following operations are supported on this resource:
GET
Retrieves a file. Technically, this operation returns the representation of a file HTTP resource whose URI is fully determined by the id query parameter that encodes the URI of the KnowledgeStore resource the file refers to. The operation:
- supports the use of HTTP preconditions in the form of If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since headers;
- allows the client to accept only representations in a certain MIME type, via Accept header;
- can enable / disable the use of server-side caches via header Cache-Control (specify no-cache or no-store to disable caches).
Parameters
| name | description | type | default |
|---|---|---|---|
| id | the URI identifier of the KnowledgeStore resource (mandatory) | query | |
| Accept | the MIME type accepted by the client (optional); a 406 NOT ACCEPTABLE response will be returned if the file representation has a non-compatible MIME type | header | */* |
Response body
the file content, on success, encoded using the specific file MIME type
Specific status codes
| HTTP Status Code | Description |
|---|---|
| 200 OK | if the file is found and its representation is returned |
| 404 Not Found | if the requested file does not exist (the associated resource may exist or not) |
Specific response headers
| Name | Description |
|---|---|
| Content-MD5 | the MD5 hash of the file representation |
| Content-Language | the 2-letters ISO 639 language code for file representation, if known |
| Content-Disposition | a content disposition directive for browsers, including the suggested file name and date for saving the file |
PUT
Creates or updates a file, uploading its content as the entity of the HTTP request. Technically, this operation stores the representation of a file HTTP resource whose URI is fully determined by the id query parameter that encodes the URI of the KnowledgeStore resource the file refers to. The operation:
- can result either in the file being created or updated;
- supports the use of HTTP preconditions in the form of If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since headers;
- can supply arbitrary metadata about the file using zero or more occurrences of the X-KS-Content-Meta property value non-standard header, where properties and values are encoded using the Turtle syntax.
Parameters
| name | description | type | default |
|---|---|---|---|
| id | the URI identifier of the KnowledgeStore resource (mandatory, must refer to an existing resource for the request to be valid) | query |
Request Body
the file to store
Response body
the operation outcome, encoded in one of the supported RDF MIME types
Specific status codes
| HTTP Status Code | Description |
|---|---|
| 200 OK | if the file has been updated |
| 201 Created | if the file has been created |
POST
Creates, updates or deletes a file, using a multipart form data HTTP entity that is compatible with the POST submission HTML forms. Technically, the operation targets the Files HTTP resource (controller), supplying all the data necessary for uploading the file in a single multipart message. The operation:
- can result either in the file being created, updated or deleted (deletion occurs if no file content is included in the multipart message);
- can supply arbitrary metadata about the file using either property = value form parameters encoded in the multipart message or by sending zero or more occurrences of the X-KS Content-Meta non-standard property value header; in both cases, properties and values are encoded using Turtle syntax.
Request Body
a multipart form data entity containing a body part for the id URI parameter (must denote an existing resource for the request to be valid), a body part for the file parameter and optional body parts for additional metadata attributes about the uploaded file
Response body
the operation outcome, encoded in one of the supported RDF MIME types
Specific status codes
| HTTP Status Code | Description |
|---|---|
| 200 OK | if the file has been updated or deleted |
| 201 Created | if the file has been created |
Specific response headers
| Name | Description |
|---|---|
| Location | the URI of the created file |
DELETE
Deletes a file. Technically, the operation targets a file HTTP resource whose URI is fully determined by the id query parameter that encodes the URI of the KnowledgeStore resource the file refers to. The operation supports the use of HTTP preconditions in the form of If-Match, If-None-Match, If-Modified-Since, If-Unmodified-Since headers.
Parameters
| name | description | type | default |
|---|---|---|---|
| id | the URI identifier of the KnowledgeStore resource (mandatory) | query |
Response body
the operation outcome, encoded in one of the supported RDF MIME types
Specific status codes
| HTTP Status Code | Description |
|---|---|
| 200 OK | if the file has been deleted |
| 404 Not Found | if the file does not exist (the associated resource may exist or not) |