bubble content-type handling up so that it can be assumed througouth

Author: ewdurbin

peps/pep-0694.rst

@@ -173,6 +173,52 @@ PEP does not modify the legacy API in any way.
 
 The API proposed in this PEP therefor has the version number ``2.0``.
 
+Content Types
+-------------
+
+Like :pep:`691`, this PEP proposes that all requests and responses from this upload API will have a
+standard content type that describes what the content is, what version of the API it represents, and
+what serialization format has been used.
+
+This standard request content type applies to all requests *except* for requests to execute
+a File Upload Mechanism, which will be specified by the documentation for that mechanism.
+
+The structure of the ``Content-Type`` header for all other requests is:
+
+.. code-block:: text
+
+    application/vnd.pypi.upload.$version+$format
+
+Since minor API version differences should never be disruptive, only the major version is included
+in the content type; the version number is prefixed with a ``v``.
+
+The major API version specified in the ``.meta.api-version`` JSON key of client requests
+**MUST** match the ``Content-Type`` header for major version.
+
+Unlike :pep:`691`, this PEP does not change the existing *legacy* ``1.0`` upload API in any way, so
+servers are required to host the new API described in this PEP at a different endpoint than the
+existing upload API.
+
+Since JSON is the only defined request format defined in this PEP, all non-file-upload requests
+defined in this PEP **MUST** include a ``Content-Type`` header value of:
+
+- ``application/vnd.pypi.upload.v2+json``.
+
+Similar to :pep:`691`, this PEP also standardizes on using server-driven content negotiation to
+allow clients to request different versions or serialization formats, which includes the ``format``
+part of the content type.  However, since this PEP expects the existing legacy ``1.0`` upload API to
+exist at a different endpoint, and this PEP currently only provides for JSON serialization, this
+mechanism is not particularly useful.  Clients only have a single version and serialization they can
+request. However clients **SHOULD** be prepared to handle content negotiation gracefully in the case
+that additional formats or versions are added in the future.
+
+Unless otherwise specified, all HTTP requests and responses in this document are assumed to include
+the HTTP header:
+
+.. code-block:: text
+
+    Content-Type: application/vnd.pypi.upload.v2+json
+
 
 Root Endpoint
 -------------
@@ -191,9 +237,7 @@ Create an Upload Session
 A release starts by creating a new upload session.  To create the session, a client submits a
 ``POST`` request to the root URL like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -244,9 +288,7 @@ Response Body
 
 The successful response includes the following content:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -375,9 +417,7 @@ to those URLs from one session to the next.
 To initiate a file upload, a client first sends a ``POST`` request to the ``upload`` URL.  The
 request looks like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -442,9 +482,7 @@ File Upload Session Response Body
 
 The successful response includes the following:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -460,8 +498,7 @@ The successful response includes the following:
         "http-post-application-octet-stream": {
           "file_url": "..."
           "attestations_url": "..."
-        },
-        ...
+        }
       }
     }
 
@@ -505,9 +542,7 @@ file upload session creation response body.
 
 The requests looks like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -588,9 +623,7 @@ or :ref:`file upload session creation response body <file-upload-session-respons
 
 The request looks like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -640,9 +673,7 @@ response body <session-response>`.
 
 The request looks like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -737,9 +768,7 @@ Errors
 
 All error responses that contain content look like:
 
-.. code-block:: text
-
-    Content-Type: application/vnd.pypi.upload.v2+json
+.. code-block:: json
 
     {
       "meta": {
@@ -834,46 +863,6 @@ containing a JSON array of :pep:`attestation objects <740#attestation-objects>`
     [{"version": 1, "verification_material": {...}, "envelope": {...}},...]
 
 
-Content Types
--------------
-
-Like :pep:`691`, this PEP proposes that all requests and responses from this upload API will have a
-standard content type that describes what the content is, what version of the API it represents, and
-what serialization format has been used.
-
-This standard request content type applies to all requests *except* for requests to execute
-a File Upload Mechanism, which will be specified by the documentation for that mechanism.
-
-The structure of the ``Content-Type`` header for all other requests is:
-
-.. code-block:: text
-
-    application/vnd.pypi.upload.$version+$format
-
-Since minor API version differences should never be disruptive, only the major version is included
-in the content type; the version number is prefixed with a ``v``.
-
-The major API version specified in the ``.meta.api-version`` JSON key of client requests
-**MUST** match the ``Content-Type`` header for major version.
-
-Unlike :pep:`691`, this PEP does not change the existing *legacy* ``1.0`` upload API in any way, so
-servers are required to host the new API described in this PEP at a different endpoint than the
-existing upload API.
-
-Since JSON is the only defined request format defined in this PEP, all non-file-upload requests
-defined in this PEP **MUST** include a ``Content-Type`` header value of:
-
-- ``application/vnd.pypi.upload.v2+json``.
-
-Similar to :pep:`691`, this PEP also standardizes on using server-driven content negotiation to
-allow clients to request different versions or serialization formats, which includes the ``format``
-part of the content type.  However, since this PEP expects the existing legacy ``1.0`` upload API to
-exist at a different endpoint, and this PEP currently only provides for JSON serialization, this
-mechanism is not particularly useful.  Clients only have a single version and serialization they can
-request. However clients **SHOULD** be prepared to handle content negotiation gracefully in the case
-that additional formats or versions are added in the future.
-
-
 FAQ
 ===