diff --git a/pep-0691.rst b/pep-0691.rst index 7aaab7c07..d8ceb5e0b 100644 --- a/pep-0691.rst +++ b/pep-0691.rst @@ -116,7 +116,7 @@ into the API, rather it describes a different serialization format for the exist features, this PEP does not change the existing ``1.0`` version, and instead just describes how to serialize that into JSON. -Simililary to :pep:`629`, the major version number **MUST** be incremented if any +Similar to :pep:`629`, the major version number **MUST** be incremented if any changes to the new format would result in no longer being able to expect existing clients to meaningfully understand the format. @@ -287,7 +287,7 @@ Content-Types ------------- This PEP proposes that all responses from the Simple API will have a standard -content type that describes what the response is (a simple api response), what +content type that describes what the response is (a Simple API response), what version of the API it represents, and what serialization format has been used. The structure of this content type will be:: @@ -362,7 +362,7 @@ This PEP **does** require that if the meta version ``latest`` is being used, the server **MUST** respond with the content type for the actual version that is contained in the response (i.e. A ``Accept: application/vnd.pypi.simple.latest+json`` request that returns -a v1.x response should have a ``Content-Type`` of +a ``v1.x`` response should have a ``Content-Type`` of ``application/vnd.pypi.simple.v1+json``). The ``Accept`` header is a comma separated list of content types that the client @@ -506,7 +506,7 @@ using the ``Accept`` header, the server can ignore it and return the content typ that corresponds to that endpoint. For clients that wish to require specific configuration, they can keep track of -which version+format a specific repository url was configured for, and when making +which version+format a specific repository URL was configured for, and when making a request to that server, emit an ``Accept`` header that *only* includes the correct content type. @@ -540,7 +540,7 @@ However, it appears that the current WIP branch against pip that attempts to imp :pep:`458` is using a target path like ``simple/PROJECT/index.html``. This could be modified to include the API version and serialization format using something like ``simple/PROJECT/vnd.pypi.simple.vN.FORMAT``. So the v1 HTML format would be -``simple/PROJECT/vnd.pypi.simple.v1.html`` and the v1 JSON format woould be +``simple/PROJECT/vnd.pypi.simple.v1.html`` and the v1 JSON format would be ``simple/PROJECT/vnd.pypi.simple.v1.json``. In this case, since ``text/html`` is an alias to ``application/vnd.pypi.simple.v1+html`` @@ -592,9 +592,9 @@ It is recommended that clients: You should generally *not* include a quality priority value for your content types, unless you have implementation specific reasons that you want the - server to take into account (for example, if you're using the stdlib html - parser and you're worried that there may be some kinds of HTML responses that - you're unable to parse in some edge cases). + server to take into account (for example, if you're using the standard library + HTML parser and you're worried that there may be some kinds of HTML responses + that you're unable to parse in some edge cases). The one exception to this recommendation is that it is recommended that you *should* include a ``;q=0`` value on the legacy ``text/html`` content type, @@ -759,7 +759,7 @@ question. For example: any form of content negotiation. In order to have a server hosted on S3, you would have to use the "Endpoint configuration" style of negotiation, and users would have to configure their clients explicitly. -- **Github Pages:** Github pages does not support custom content types, so the +- **GitHub Pages:** GitHub pages does not support custom content types, so the S3 solution is not currently workable, which means that only ``text/html`` repositories would function. - **Apache:** Apache fully supports server-driven content negotiation, and would @@ -808,7 +808,7 @@ it be updated to be an alias for ``application/vnd.pypi.simple.v2+json``? This problem doesn't exist for ``text/html``, because the assumption is that HTML will remain a legacy format, and will likely not gain *any* new features, -much less features that require breaking compatability. So having it be an +much less features that require breaking compatibility. So having it be an alias for ``application/vnd.pypi.simple.v1+html`` is effectively the same as having it be an alias for ``application/vnd.pypi.simple.latest+html``, since ``1.0`` will likely be the only HTML version to exist. @@ -816,8 +816,8 @@ having it be an alias for ``application/vnd.pypi.simple.latest+html``, since The largest benefit to adding the ``application/json`` content type is that there do things that do not allow you to have custom content types, and require you to select one of their preset content types. The main example of this being -Github Pages, which the lack of ``application/json`` support in this PEP means -that static repositories will no longer be able to be hosted on Github Pages +GitHub Pages, which the lack of ``application/json`` support in this PEP means +that static repositories will no longer be able to be hosted on GitHub Pages unless GitHub adds the ``application/vnd.pypi.simple.v1+json`` content type. This PEP believes that the benefits are not large enough to add that content