Version: SWORD 3.0

Last modified: 2021-09-01 09:54

This document provides details of the specific protocol requirements for every operation that SWORD 3.0 supports.

See also: SWORD 3.0 Specification from which this document of denormalised protocol operations is derived.

Each section describes the operation you can perform, and then the technical details of performing it, as follows:

• Protocol Operation: the HTTP request verb on the resource URL to be used
• Request Requirements: The burdens on the client making this request
• Server Requirements: The ways in which the server should treat the request
• Response Requirements: On a successful request, the requirements on the server when responding to the client
• Error Responses: In the case of an error, which errors to respond with under each circumstance

1. Retrieve the Service Document

Request from the server a list of the Service-URLs that the client can deposit to. A Service-URL allows the server to support multiple different deposit conditions - each URL may have its own set of rules/workflows behind it; for example, Service-URLs may be subject-specific, organisational-specific, or process-specific. It is up to the client to determine which is the suitable URL for its deposit, based on the information provided by the server. The list of Service-URLs may vary depending on the authentication credentials supplied by the client.

This request can be made against a root Service-URL, which will describe the capabilities of the entire server, for information about the full list of Service-URLs, or can be made against an individual Service-URL for information just about that service.

Protocol Operation

• GET Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST only list Service-URLs in the Service Document for which a deposit request would be permitted
• MUST respond with a valid Service Document or a suitable error response

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

2. Creating New Objects

2.1. Creating Objects with no content

Create a new Object on the server with no metadata or binary content. That is, create a container into which you can subsequently send data. It is RECOMMENDED that when using this route you specify In-Progress: true.

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

2.2. Creating Objects with only Metadata

Create a new Object on the server, sending only Metadata content (i.e. no Binary File content, and no By-Reference Files).

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide only the Metadata Document
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.
• If accepting the request MUST populate the Object with the supplied Metadata

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

2.3. Creating Objects with only By-Reference Files

Create a new Object on the server, sending on By-Reference Files (i.e. no Binary Files and no Metadata)

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the By-Reference Document
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.
• If accepting the request MUST attach the By-Reference files to the Object.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

2.4. Creating Objects with both Metadata and By-Reference Files

Create a new Object on the server, sending both Metadata content and By-Reference Files (i.e. no Binary File content)

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide the Metadata+By Reference Document
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.
• If accepting the request MUST populate the Object with the supplied Metadata, and attach the By-Reference files to it.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

2.5. Creating Objects with Binary Files

Create a new Object on the server, sending a single Binary File. The Binary File is an opaque bitstream which the server should not attempt to unpack.

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MAY provide the Packaging header, and if so MUST be the Binary format identifier
• MUST provide Binary File body content
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server SHOULD NOT attempt to unpack the file
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

2.6. Creating Objects with Packaged Content

Create a new Object on the server, sending a single Binary File. The Binary File itself is specified as Packaged Content, which the server may understand how to unpack.

Protocol Operation

• POST Service-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the Packaging header
• MUST provide Packaged Content in the request body
• MAY provide the Slug header
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server MAY attempt to unpack the file, and create derivedResources from it.
• If a Slug header is provided, MAY use this as the identifier for the newly created Object.
• If accepting the request MUST create a new Object
• If no In-Progress header is provided, MUST assume that it is false
• If In-Progress is false, SHOULD expect further updates to the item, and not progress it through any ingest workflows yet.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a Location header, containing the Object-URL
• MUST respond with a valid Status Document or a suitable error response
• Status Document MUST be available on GET to the Object-URL in the Location header immediately (irrespective of whether this is a 201 or 202 response)
• MUST respond with a 201 if the item was created immediately, a 202 if the item was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the server does not accept packages in the format identified in the Packaging header, MUST respond with a 415 (PackagingFormatNotAcceptable)
• If the Packaging header does not match the format found in the body content, SHOULD return 415 (FormatHeaderMismatch). Note that the server may not be able to inspect the package during the request-response, so MAY NOT return this response.

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

2.7. Creating Objects with Segmented File Upload

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Creating Objects with only By-Reference Files

3. Retrieving all or part of Objects

3.1. Retrieving an Object's Status

For an Object where you have an Object-URL, you may request information about the current state of that resource, and receive the Status document in response.

Protocol Operation

• GET Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

3.2. Retrieving the Metadata from an Object

Retrieve the descriptive Metadata document associated with the Object in the standard SWORD format. This operation is done against the Metadata-URL, which is the resource URL representing the Object’s metadata. When retrieved, this resource is serialised only as the standard SWORD format, content negotiation is not supported. If you want to retrieve the metadata for the Object in other formats, you can see a list of the available formats in the Status document, and the individual expressions of the metadata can then be retrieved directly by the appropriate URL.

Protocol Operation

• GET Metadata-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST respond with a valid Metadata Document (see definition below) or a suitable error response

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

3.3. Retrieving a Binary File from an Object

Retrieve a single File from the Object; files available for retrieval are listed in the Status document. These single files could be actual individual files that make up the object, or:

• Packaged Content that contains a full representation of the Object, including all its files and metadata, packaged according to some standard.
• Metadata in specific formats supported by the server

Protocol Operation

• GET File-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST respond with a File (which may be Packaged Content, a Binary File, a Metadata Document, or any other file that the server exposes) or a suitable error response

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

3.4. Retrieving a Packaged Content representation of an Object

To retrieve the full Object packaged according to some Packaging format, the Status document contains all the files that the Object contains, and identifies those which allow you to retrieve the entire objects as a package. Use the Status document to obtain the URL for the format you wish to retrieve, and make a GET to that URL. See the section "Retrieving a Binary File from an Object" for the specification of this operation.

4. Appending to existing Objects

Metadata and Files may be added to existing Objects through a variety of mechanisms, which are listed in this section.

4.1. Appending Metadata to an Object

Append new metadata to an Object. Metadata provided in this way should be considered to extend existing metadata, such that any new metadata fields are added to the Object, and any existing metadata fields are kept as-is.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide only the Metadata Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new Metadata MUST add the Metadata to the item, and only treat this as an extension to existing Metadata. The server MUST NOT overwrite or otherwise remove existing Metadata.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

4.2. Appending By-Reference Files to an Object

Append new files to an Object by sending one or more By-Reference files.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the By-Reference Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the request, MUST attach all the By-Reference files to the Object as originalDeposits

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

4.3. Appending Metadata and By-Reference Files to an Object

Append new files and append/overlay Metadata at the same time.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide the Metadata+By Reference Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the request, MUST attach all the By-Reference files to the Object as originalDeposits, and MUST add the Metadata to the item, and only treat this as an extension to existing Metadata. The server MUST NOT overwrite or otherwise remove existing Metadata.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

4.4. Appending a single Binary File to an Object

Append new File to the Object, in addition to existing content which it already contains. This File will be added as-is to the Object, without the server unpacking it as it would Packaged Content.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MAY provide the Packaging header, and if so MUST be the Binary format identifier
• MUST provide Binary File body content
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server SHOULD NOT attempt to unpack the file
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.
• MUST respond with a Location header, containing the File-URL of the Original Deposit File

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

4.5. Appending Packaged Content to an Object

Append new Files (via Packaged Content) to the Object, in addition to existing content which it already contains. The package may be unpacked by the server and new file resources added. Metadata may also be appended/selectively updated, if the package contains actionable metadata.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the Packaging header
• MUST provide Packaged Content in the request body
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server MAY attempt to unpack the file, and create derivedResources from it.
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.
• MUST respond with a Location header, containing the File-URL of the Original Deposit File

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the server does not accept packages in the format identified in the Packaging header, MUST respond with a 415 (PackagingFormatNotAcceptable)
• If the Packaging header does not match the format found in the body content, SHOULD return 415 (FormatHeaderMismatch). Note that the server may not be able to inspect the package during the request-response, so MAY NOT return this response.
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

4.6. Append of Binary Files to an Object via Segmented File Upload

Append a single Binary File to an Object which will be delivered via a Segmented File Upload.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Appending By-Reference Files to an Object

4.7. Append of Packaged Content to an Object via Segmented File Upload

As Append of Binary Files to an Object via Segmented File Upload.

5. Replacing all or part of existing Objects

Metadata and Files may be replaced in existing Objects through a variety of mechanisms, which are listed in this section.

5.1. Replacing the Metadata of an Object

Replace in its entirety the Metadata associated with an Object.

Protocol Operation

• PUT Metadata-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide only the Metadata Document
• MUST include the If-Match header, if the server implements concurrency control

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If accepting the new Metadata MUST entirely replace the existing Metadata with the new.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a 204 if the replacement was deposited immediately, a 202 if the replacement was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

5.2. Replacing a single File in an Object

Replace an existing file in the Object with a new file. The server may keep the old version of the file available.

Protocol Operation

• PUT File-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MAY provide the Packaging header, and if so MUST be the Binary format identifier
• MUST provide Binary File body content
• MUST include the If-Match header, if the server implements concurrency control

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server SHOULD NOT attempt to unpack the file
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If accepting the new File, MUST replace the existing File. The server MAY keep the previous file as an older version. The new File MUST be marked as an originalDeposit

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a 204 if the replacement was deposited immediately, a 202 if the replacement was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.3. Replacing a single File in an Object with a By-Reference File

Replace an existing file in the Object with a new file which the server retrieves as a By-Reference File. The server may keep the old version of the file available.

Protocol Operation

• PUT File-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the By-Reference Document
• MUST only include a single By-Reference File in the By-Reference Document
• MUST include the If-Match header, if the server implements concurrency control

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• If more than one By-Reference File is present, MUST reject the request.
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If accepting the new By-Reference File, MUST replace the existing File. The server MAY keep the previous file as an older version. The new file MUST be marked as an originalDeposit

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a 204 if the replacement was deposited immediately, a 202 if the replacement was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• If rejecting the request due to the presence of more than one By-Reference File in the By-Reference Document, MUST respond with a 400 (BadRequest)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.4. Replacing a single File in an Object with a Segmented Upload

Replace an existing file in the Object with a new file, which the client will send in segments.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing a single File in an Object with a By-Reference File

5.5. Replacing the FileSet of an Object with By-Reference Files

Replace all the files in the FileSet of an Object with one or more By-Reference Files. All previously existing files will be removed, and new ones will replace them. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

• PUT FileSet-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the By-Reference Document
• MUST include the If-Match header, if the server implements concurrency control

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If accepting the new By-Reference Files, MUST replace the existing FileSet with the new files. The server MUST remove all the old files immediately, even before the new By-Reference files have been dereferenced. The new Files MUST be marked as originalDeposits

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a 204 if the replacement was deposited immediately, a 202 if the replacement was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.6. Replacing the FileSet of an Object with a single Binary File

Replace in its entirety the FileSet of the Object (i.e. not the Metadata), with a single Binary File. All previously existing files will be removed, and the new one will replace them. The server may or may not keep old versions of the content available, at its discretion.

Note that we can only send a single Binary File to replace the FileSet, we cannot send a package, as a package implies the presence of metadata which the FileSet-URL is not suitable to handle.

Protocol Operation

• PUT FileSet-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MAY provide the Packaging header, and if so MUST be the Binary format identifier
• MUST provide Binary File body content
• MUST include the If-Match header, if the server implements concurrency control

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server SHOULD NOT attempt to unpack the file
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If accepting the new File, MUST replace the existing FileSet with a single new File. The File MUST be marked as an originalDeposit

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a 204 if the replacement was deposited immediately, a 202 if the replacement was queued for import, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.7. Replacing the FileSet of an Object with a single Binary File via Segmented File Upload

Replace in its entirity the FileSet of the Object (i.e. not the Metadata), with a single Binary File, that is provided via Segmented File Upload. All previously existing files will be removed, and the new one will replace them. The server may or may not keep old versions of the content available, at its discretion.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing the FileSet of an Object with By-Reference Files

5.8. Replacing an Object with Metadata only

Replace the entire Object, removing all previous files and metadata, and replace it with just the supplied Metadata. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

• PUT Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide only the Metadata Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new Metadata, MUST remove all existing Files from the Object, and MUST replace the existing Metadata with the new.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true

5.9. Replacing an Object with By-Reference Files only

Replace the entire Object, removing all previous files and metadata, and replace it with one or more files supplied via By-Reference upload. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

• PUT Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the By-Reference Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new By-Reference files, MUST remove all existing Files from the Object and replace with the By-Reference files. The server MUST remove the existing Files immediately, even before the By-Reference files have dereferenced. The new files MUST be marked as originalDeposits. The server MUST also remove all Metadata, so the Metadata Resource contains no fields.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; by-reference=true

5.10. Replacing an Object with Metadata and By-Reference Files

Replace the entire Object, removing all previous files and metadata, and replace it with new Metadata and one or more files supplied via By-Reference upload. The server may or may not keep old versions of the content available, at its discretion.

Protocol Operation

• PUT Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• SHOULD provide the Metadata-Format header
• MUST provide the Metadata+By Reference Document
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If no Metadata-Format header is provided, MUST assume this is the standard SWORD format: http://purl.org/net/sword/3.0/types/Metadata
• If downloading copies of the files in the By-Reference Document, MUST do this asynchronously to the deposit request
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new Metadata and By-Reference files, MUST remove all existing Files from the Object and replace with the By-Reference files. The server MUST remove the existing Files immediately, even before the By-Reference files have dereferenced. The server MUST also replace all existing Metadata with the new Metadata.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If rejecting the request due to the announced file size, MUST respond with a 400 (ByReferenceFileSizeExceeded)
• If the server does not support By-Reference, MUST respond with a 412 (ByReferenceNotAllowed)
• If the Metadata-Format header does not match the format found in the body content, MAY return 415 (FormatHeaderMismatch)
• If the Metadata-Format header indicates a format the server does not support, MUST return 415 (MetadataFormatNotAcceptable)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; metadata=true; by-reference=true

5.11. Replacing an Object with a single Binary File

Replace in its entirety the Object, including all Metadata and Files, with the single Binary File. All previous files and metadata will be removed, and new ones will replace them (the updated item will have no Metadata, though). The server may or may not keep old versions of the content available.

Protocol Operation

• PUT Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MAY provide the Packaging header, and if so MUST be the Binary format identifier
• MUST provide Binary File body content
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server SHOULD NOT attempt to unpack the file
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new File, MUST remove all existing Files from the Object and replace with the new File. The new File should be marked as an originalDeposit. The server MUST also remove all Metadata, so the Metadata Resource contains no fields.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.12. Replacing an Object with Packaged Content

Replace in its entirety the Object, including all Metadata and Files, with the Metadata and Files contained in the Packaged Content. All previous files and metadata will be removed, and new ones will replace them. The server may or may not keep old versions of the content available.

Protocol Operation

• PUT Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length
• MUST provide the Content-Type header
• MUST provide the Packaging header
• MUST provide Packaged Content in the request body
• MUST include the If-Match header, if the server implements concurrency control
• MAY provide the In-Progress header

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• If all preconditions are met, MUST either accept the deposit request immediately, queue the request for processing, or respond with an error
• If accepting the request MUST attach the supplied file to the Object as an originalDeposit
• The server MAY attempt to unpack the file, and create derivedResources from it.
• MUST reject the request if the If-Match header does not match the current ETag of the resource
• If no In-Progress header is provided, MUST assume that it is false
• If accepting the new File, MUST remove all existing Files from the Object and replace with the new File. The new File should be marked as an originalDeposit. The server MUST also remove all Metadata, so the Metadata Resource contains no fields.

Response Requirements

• MUST include ETag header if implementing concurrency control
• MUST include one or more File-URLs for the deposited content in the Status document. The behaviour of these File-URLs may vary depending on the type of content deposited (e.g. ByReference and Segmented Uploads do not need to be immediately retrievable)
• MUST respond with a valid Status Document or a suitable error response
• MUST include ETag header if implementing concurrency control
• MUST respond with a 200 if the request was accepted immediately, a 202 if the request was queued for processing, or raise an error.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the Content-Type header contains a format that the server cannot accept, MUST respond with 415 (ContentTypeNotAcceptable)
• If the body content is larger than the maximum allowed by the server, MAY return 413 (MaxUploadSizeExceeded)
• If the server does not accept packages in the format identified in the Packaging header, MUST respond with a 415 (PackagingFormatNotAcceptable)
• If the Packaging header does not match the format found in the body content, SHOULD return 415 (FormatHeaderMismatch). Note that the server may not be able to inspect the package during the request-response, so MAY NOT return this response.
• For servers implementing concurrency control, if the If-Match header does not match the current ETag, MUST respond with 412 (ETagNotMatched)
• For servers implementing concurrency control, if no If-Match header is provided, MUST respond with 412 (ETagRequired)

The Content-Disposition in this case would be:

Content-Disposition: attachment; filename=[filename]

5.13. Replacing an Object with a single Binary File via Segmented File Upload

Replace in its entirety the Object, including all Metadata and Files, with a single Binary File, which will be delivered via Segmented File Upload. All previous files and metadata will be removed, and new ones will replace them. The server may or may not keep old versions of the content available.

First create a Temporary-URL to which to upload the file segments:

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

Then upload all the file segments as per Upload a File Segment.

Then carry out a By-Reference deposit using the Temporary-URL as per Replacing an Object with By-Reference Files only

5.14. Replacing an Object with Packaged Content via Segmented File Upload

This operation is carried out exactly as per Replacing an Object with a single Binary File via Segmented File Upload.

6. Deleting all or part of Objects

6.1. Deleting an Object's Metadata

Delete all the metadata fields from the Object.

Protocol Operation

• DELETE Metadata-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 204 if the delete is successful, 202 if the delete is queued for processing, or raise an error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

6.2. Deleting a single Binary File from an Object

Delete a single File from the Object. The server may keep old versions of the file.

Protocol Operation

• DELETE File-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 204 if the delete is successful, 202 if the delete is queued for processing, or raise an error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

6.3. Deleting all the Files from an Object

Remove all the Files from an object. This will leave the Object and its Metadata intact. The server may keep old versions of the files available.

Protocol Operation

• DELETE FileSet-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 204 if the delete is successful, 202 if the delete is queued for processing, or raise an error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

6.4. Deleting the entire Object

Delete the Object in its entirety from the server, along with all Metadata and Files.

Protocol Operation

• DELETE Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 204 if the delete is successful, 202 if the delete is queued for processing, or raise an error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

7. File Segments

7.1. Initialise a Segmented File Upload

Protocol Operation

• POST Staging-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• If all preconditions are met, MUST create a resource to which the client can upload file segments
• MUST reject the request if the conditions of the upload are not acceptable

Response Requirements

• MUST respond with a 201 to indicate that the Segmented Upload has been initialised, or raise an error.
• MUST respond with a Location header containing the Temporary-URL where the client can upload file segments

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If the proposed final assembled file size is larger than the server's limit, MUST return 400 (MaxAssembledSizeExceeded)
• If the proposed segment size is not within the parameters the server supports, MUST return 400 (InvalidSegmentSize)
• If the proposed number of segments is not within the parameters the server supports, MUST return 400 (SegmentLimitExceeded)

The Content-Disposition in this case would be:

Content-Disposition: segment-init; size=[bytes]; digest=[digest]; segment_count=[n]; segment_size=[bytes]

7.2. Upload a File Segment

Protocol Operation

• POST Temporary-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the Content-Disposition header, with the appropriate value for the request
• MUST provide the Digest header
• SHOULD provide the Content-Length

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MUST verify that the content matches the Digest header
• MUST verify that the supplied content matches the Content-Length if this is provided
• MUST reject the request if the segment is incorrect or unexpected: for example, all segments were already received, or the segment is a different size than expected.
• If all preconditions are met, MUST accept the file segment, and record the receipt of it
• MUST be prepared to accept file segments in any order, and in parallel
• MUST be able to store the incoming file segments as they arrive, and then reconstitute them into a single file when all segments have been received.

Response Requirements

• MUST respond with a 204 or a suitable error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)
• If one or more of the digests provided by the client that the server checked did not match, MAY respond with 412 (DigestMismatch). Note that servers MAY NOT check digests in real-time.
• If the body content could not be read correctly, MAY return a 400 (ContentMalformed)
• If the provided segment is not the final segment and is not the size that the client had indicated on initialisation, MUST return 400 (InvalidSegmentSize)
• If the Temporary-URL has expired, SHOULD return 410 (SegmentedUploadTimedOut). Servers may also return 404 and no further explanation.
• If the segment was not expected, for example all the expected segments have already been sent, or a segment with this segment number has already been received, MUST return 400 (UnexpectedSegment)

The Content-Disposition in this case would be:

Content-Disposition: segment; segment_number=[n]

7.3. Abort a Segmented File Upload

Protocol Operation

• DELETE Temporary-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 204 if the delete is successful, 202 if the delete is queued for processing, or raise an error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

7.4. Retrieve information about a Segmented File Upload

Protocol Operation

• GET Temporary-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request

Response Requirements

• MUST respond with a 200 or a suitable error
• If successful, MUST respond with a Segmented File Upload Document describing the current state of the upload.

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

8. Completing Previously In-Progress Deposits

Where you have previously carried out deposits and sent the object the In-Progress: true header, you will eventually need to tell the server that you have completed your additions or modifications to the Object, so that it can finalise your deposit.

Protocol Operation

• POST Object-URL

Request Requirements

• MAY specify Authorization and On-Behalf-Of headers (i.e. if authenticating this request)
• MUST provide the header In-Progress: false
• MAY provide the Content-Length header with value 0
• MUST NOT include any body content

Server Requirements

• If Authorization (and optionally On-Behalf-Of) headers are provided, MUST authenticate the request
• MAY inject the content into any ingest workflows

Response Requirements

• MUST respond with a 204 or a suitable error

Error Responses

• If no authentication credentials were supplied, but were expected, MUST respond with a 401 (AuthenticationRequired)
• If authentication fails with supplied credentials, MUST respond with a 403 (AuthenticationFailed)
• If the server does not allow this method in this context at this time, MAY respond with a 405 (MethodNotAllowed)
• If the server does not support On-Behalf-Of deposit and the On-Behalf-Of header has been provided, MAY respond with a 412 (OnBehalfOfNotAllowed)

No Content-Disposition header is required in this request.