Move some text around so it flows better

Author: warsaw

peps/pep-0694.rst

@@ -346,8 +346,11 @@ The request includes the following top-level keys:
     **MUST** conform to the `packaging version
     <https://packaging.python.org/en/latest/specifications/version-specifiers/>`_ specification.
 
-Upon successful session creation, the server returns a ``201 Created`` response.  If an error
-occurs, the appropriate ``4xx`` code will be returned, as described in the :ref:`session-errors`
+Upon successful session creation, the server returns a ``201 Created`` response.  The response **MUST** also
+include a ``Location`` header containing the same URL as the :ref:`links.session <publishing-session-links>`
+key in the :ref:`response body <publishing-session-response>`.
+
+If an error occurs, the appropriate ``4xx`` code will be returned, as described in the :ref:`session-errors`
 section.
 
 If a session is created for a project which has no previous release,
@@ -362,7 +365,6 @@ The session is owned by the user that created it,
 and all subsequent requests **MUST** be performed with the same credentials,
 otherwise a ``403 Forbidden`` will be returned on those subsequent requests.
 
-
 .. _publishing-session-response:
 
 Response Body
@@ -416,12 +418,12 @@ the following keys:
     including any uploaded files and the URL links related to the session. The session **SHOULD**
     remain active until at least this time unless the client itself has canceled or published the
     session. Servers **MAY** choose to extend this expiration time, but should never move it
-    earlier.  Clients can query the :ref:`session status <session-status>` to get the current
+    earlier.  Clients can query the :ref:`session status <publishing-session-status>` to get the current
     expiration time of the session.
 
 ``status``
     A string that contains one of ``pending``, ``published``, ``error``, or ``canceled``,
-    representing the overall :ref:`status of the session <session-status>`.
+    representing the overall :ref:`status of the session <publishing-session-status>`.
 
 ``files``
     A mapping containing the filenames that have been uploaded to this session, to a mapping
@@ -432,6 +434,19 @@ the following keys:
     wishes to communicate to the end user.  These notices are specific to the overall session, not
     to any particular file in the session.
 
+.. _publishing-session-multiple:
+
+Multiple Session Creation Requests
+++++++++++++++++++++++++++++++++++
+
+If a second session is created for the same name-version pair while a session for that pair is in the
+``pending``, ``processing``, or ``complete`` state, then the server **MUST** respond with a ``409 Conflict``
+and **MUST** include a ``Location`` header that points to the :ref:`session status URL
+<publishing-session-status>`.
+
+For sessions in the ``error`` or ``canceled`` state, a new session is created with same ``201 Created``
+response and payload, except that the :ref:`publishing session status URL <publishing-session-status>`,
+``session-token``, and ``links.stage`` values **MUST** be different.
 
 .. _publishing-session-links:
 
@@ -440,6 +455,14 @@ Publishing Session Links
 
 For the ``links`` key in the success JSON, the following sub-keys are valid:
 
+``session``
+    The endpoint where actions for this session can be performed,
+    including :ref:`publishing this session <publishing-session-completion>`,
+    :ref:`canceling and discarding the session <publishing-session-cancellation>`,
+    :ref:`querying the current session status <publishing-session-status>`,
+    and :ref:`requesting an extension of the session lifetime <publishing-session-extension>`
+    (*if* the server supports it).
+
 ``upload``
     The endpoint session clients will use to initiate a :ref:`File Upload Session <file-upload-session>`
     for each file to be included in this session.
@@ -451,14 +474,6 @@ For the ``links`` key in the success JSON, the following sub-keys are valid:
     ``stage`` URL should be easily calculated using the ``session-token``, but the exact format of that URL is
     index specific.  If the index does not support previewing staged releases, this key **MUST** be omitted.
 
-``session``
-    The endpoint where actions for this session can be performed,
-    including :ref:`publishing this session <publishing-session-completion>`,
-    :ref:`canceling and discarding the session <publishing-session-cancellation>`,
-    :ref:`querying the current session status <session-status>`,
-    and :ref:`requesting an extension of the session lifetime <session-extension>`
-    (*if* the server supports it).
-
 
 .. _publishing-session-files:
 
@@ -489,10 +504,6 @@ sub-mapping with the following keys:
     An optional key with similar format and semantics as the ``notices`` session key, except that
     these notices are specific to the referenced file.
 
-If a second session is created for the same name-version pair while a session for that pair is in
-the ``pending`` state, then the server **MUST** return the JSON status response for the already
-existing session, along with the ``200 OK`` status code rather than creating a new, empty session.
-
 
 .. _publishing-session-completion:
 
@@ -521,16 +532,17 @@ If the server is able to immediately complete the Publishing Session, it may do
 request), then it may return a ``202 Accepted`` response.
 
 The server **MUST** include a ``Location`` header in the response pointing back to the :ref:`Publishing
-Session status <session-status>` URL, which can be used to query the current session status.  If the server
+Session status <publishing-session-status>` URL, which can be used to query the current session status.  If the server
 returned a ``202 Accepted``, polling that URL can be used to watch for session status changes.
 
 If an error occurs, the appropriate ``4xx`` code should be returned, as described in the
 :ref:`session-errors` section.
 
+
 .. _publishing-session-cancellation:
 
-Cancellation
-~~~~~~~~~~~~
+Publishing Session Cancellation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To cancel a Publishing Session, a client issues a ``DELETE`` request to
 the ``session`` :ref:`link <publishing-session-links>`
@@ -543,7 +555,53 @@ Future attempts to access that session URL or any of the Publishing Session URLs
 To prevent dangling sessions, servers may also choose to cancel timed-out sessions on their own
 accord. It is recommended that servers expunge their sessions after no less than a week, but each
 server may choose their own schedule.  Servers **MAY** support client-directed :ref:`session
-extensions <session-extension>`.
+extensions <publishing-session-extension>`.
+
+
+.. _publishing-session-status:
+
+Publishing Session Status
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At any time, a client can query the status of a session by issuing a ``GET`` request to the URL given in the
+:ref:`links.session <publishing-session-links>` URL (also provided in the :ref:`session creation response's
+<publishing-session-response>` ``Location`` header).
+
+The server will respond to this ``GET`` request with the same :ref:`publishing session creation response
+<publishing-session-response>`, that they got when they initially created the publishing session, except with
+any changes to ``status``, ``expires-at``, or ``files`` reflected.
+
+
+.. _publishing-session-extension:
+
+Publishing Session Extension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Servers **MAY** allow clients to extend sessions, but the overall lifetime and number of extensions
+allowed is left to the server.  To extend a session, a client issues a ``POST`` request to the
+:ref:`links.session <publishing-session-links>` URL (same as above, also the ``Location`` header).
+
+The request looks like:
+
+.. code-block:: json
+
+    {
+      "meta": {
+        "api-version": "2.0"
+      },
+      "action": "extend",
+      "extend-for": 3600
+    }
+
+The number of seconds specified is just a suggestion to the server for the number of additional seconds to
+extend the current session.  For example, if the client wants to extend the current session for another hour,
+``extend-for`` would be ``3600``.  Upon successful extension, the server will respond with the same
+:ref:`publishing session creation response body <publishing-session-response>` that they got when they
+initially created the publishing session, except with any changes to ``status``, ``expires-at``, or ``files``
+reflected.
+
+If the server refuses to extend the session for the requested number of seconds, it **MUST** still return a
+success response, and the ``expires-at`` key will simply reflect the current expiration time of the session.
 
 
 .. _publishing-session-token:
@@ -646,7 +704,7 @@ the file to be uploaded.  These checks may include, but are not limited to:
 - checking if the contents of the ``metadata``, if provided, are valid.
 
 If the server determines that upload should proceed, it will return a ``202 Accepted`` response, with the
-response body below.  The :ref:`status <session-status>` of the session will also include the filename in the
+response body below.  The :ref:`status <publishing-session-status>` of the session will also include the filename in the
 ``files`` mapping.  If the server cannot proceed with an upload because the ``mechanism`` supplied by the
 client is not supported it **MUST** return a ``422 Unprocessable Content``.  The server **MAY** allow parallel
 uploads of files, but is not required to. If the server determines the upload cannot proceed, it **MUST**
@@ -666,7 +724,6 @@ The successful response includes the following:
         "api-version": "2.0"
       },
       "links": {
-        "publishing-session": "...",
         "file-upload-session": "..."
       },
       "status": "pending",
@@ -712,14 +769,13 @@ File Upload Session Links
 
 For the ``links`` key in the success JSON, the following sub-keys are valid:
 
-``publishing-session``
-    The endpoint where actions for the parent Publishing Session can be performed.
+**FIXME**: file-upload-session, rename and add status.
 
 ``file-upload-session``
     The endpoint where actions for this file-upload-session can be performed.
     including :ref:`canceling and discarding the File Upload Session <file-upload-session-cancelation>`,
-    :ref:`querying the current File Upload Session status <session-status>`,
-    and :ref:`requesting an extension of the File Upload Session lifetime <session-extension>`
+    :ref:`querying the current File Upload Session status <publishing-session-status>`,
+    and :ref:`requesting an extension of the File Upload Session lifetime <publishing-session-extension>`
     (*if* the server supports it).
 
 .. _file-upload-session-completion:
@@ -795,63 +851,6 @@ This means providing the metadata request again to retrieve a new upload resourc
 Clients **MUST NOT** assume that the previous upload resource URL can be reused after deletion.
 
 
-.. _session-status:
-
-Session Status
---------------
-
-At any time, a client can query the status of a session by issuing a ``GET`` request to the
-``publishing-session`` :ref:`link <publishing-session-links>`
-or ``file-upload-session`` :ref:`link <file-upload-session-links>`
-given in the :ref:`session creation response body <publishing-session-response>`
-or :ref:`File Upload Session creation response body <file-upload-session-response>`,
-respectively.
-
-The server will respond to this ``GET`` request with the same
-:ref:`Publishing Session creation response body <publishing-session-response>`
-or :ref:`File Upload Session creation response body <file-upload-session-response>`,
-that they got when they initially created the Publishing Session or File Upload Session,
-except with any changes to ``status``, ``expires-at``, or ``files`` reflected.
-
-
-.. _session-extension:
-
-Session Extension
------------------
-
-Servers **MAY** allow clients to extend sessions, but the overall lifetime and number of extensions
-allowed is left to the server.  To extend a session, a client issues a ``POST`` request to the
-``publishing-session`` :ref:`link <publishing-session-links>`
-or ``file-upload-session`` :ref:`link <file-upload-session-links>`
-given in the :ref:`Publishing Session creation response body <publishing-session-response>`
-or :ref:`File Upload Session creation response body <file-upload-session-response>`,
-respectively.
-
-The request looks like:
-
-.. code-block:: json
-
-    {
-      "meta": {
-        "api-version": "2.0"
-      },
-      "action": "extend",
-      "extend-for": 3600
-    }
-
-The number of seconds specified is just a suggestion to the server for the number of additional
-seconds to extend the current session.  For example, if the client wants to extend the current
-session for another hour, ``extend-for`` would be ``3600``.  Upon successful extension, the server
-will respond with the same
-:ref:`Publishing Session creation response body <publishing-session-response>`
-or :ref:`File Upload Session creation response body <file-upload-session-response>`,
-that they got when they initially created the Publishing Session or File Upload Session,
-except with any changes to ``status``, ``expires-at``, or ``files`` reflected.
-
-If the server refuses to extend the session for the requested number of seconds, it still returns a
-success response, and the ``expires-at`` key will simply reflect the current expiration time of
-the session.
-
 .. _staged-preview:
 
 Stage Previews