Upload Profile

profile: <https://level3.rest/profiles/upload>

The Upload profile accepts byte-based payload submissions. The Upload resource can be thought to create a Content resource representing the submitted content.

Discovery

The Upload profile presents the required profile and allow headers.

Submit Content

Submit a content request to the resource. Clients are encouraged to send the content-length and content-type headers if known. The resource may require content-length and send back 411 Length Required to the client if a request omits it. The resource may respond with rejection status codes for size and media type failures.

Clients can optionally send a slug header that can be used to identify the submitted content later. The slug can be a file name, a title, or anything that helps identify the content. The slug’s text may show up in the Content’s URL, and possibly the content-disposition header. For more details on the slug header, please refer to the Atom publishing protocol.

The POST response headers include the newly-created Content resource’s URL in location as well as its Entity validation headers (etag, last-modified) if available.

No Multipart Content

1. HTTP 1.1 provides a way to mix multiple content parts in a single request with the Multipart content type. Upload chooses not to support Multipart uploads, however, for two reasons:

   1. Impossible to discover part submission requirements. Level 3’s primary architecture quality is Discoverability. To learn how to use a resource, one must be able to discover its affordances without external documentation or other out-of-band communication. Multipart does not provide this type of discovery mechanism, and the client must rely on other sources to learn what part types are acceptable and what is an acceptable submission format.
   2. HTTP/2 makes Multipart less relevant. Multipart solves a batching problem where a client wants to send multiple submissions in a single batched request. HTTP/2 makes it easier to send multiple submissions without requiring the complexity of Multipart requests. HTTP/2 uses request multiplexing and HTTP pipelining to manage simultaneous uploads over a single connection.

Mixins

Preflight Mixin

The Preflight profile mixin allows a client to validate content submission before sending a payload. The client must send content-length and content-type as preflight headers.

Specifications

HTTP/1.1 Message Syntax and Routing: RFC 7230

• content-length: section 3.3.2

HTTP/1.1 Semantics and Content: RFC 7231

• content-type: section 3.1.1.5
• 200 OK: section 6.3.1
• 201 Created: section 6.3.2
• 411 Length Required: section 6.5.10
• 413 Payload Too Large: section 6.5.11
• 415 Unsupported Media Type: section 6.5.13
• HTTP-date: section 7.1.1.1
• location: section 7.1.2

Conditional Requests: RFC 7232

• last-modified: section 2.2
• etag: section 2.3

The Atom Publishing Protocol: RFC 5023

• slug: section 9.7

© 2019-2023 Matt Bishop

This work is licensed under a Creative Commons Attribution-NoDerivatives 4.0 International License.

Tweet about Level 3 REST