Unnecessary link to HTTP 1.1 header definition

[Martin Geisler]

After the two curl examples, I see this sentence:

  For a complete description of HTTP 1.1 header definitions, see Header Field Definitions.

There is a link to the RFC 2616, which defines HTTP 1.1. This feels unnecessary and unhelpful to me.

My reasoning is that linking to the RFC with its BNF descriptions of the legal syntax for each header is too detailed. A developer reading the Swift API docs will want to know the headers supported by Swift. Such a developer would already know what a header is and the general syntax of a HTTP header. If he's interested in a list of all the HTTP 1.1 headers, he would surely be able to google for it and find better (more succient) lists than the RFC itself -- an RFC is a reference document, not something that is normally consulted when reading API docs.

The other pages follow the same template and I would remove the links in all of them.

-----------------------------------
Built: 2014-05-10T16:25:08 00:00
git SHA: 66f6363b99ab396ad5150447bb87fa931d364801
URL: http://docs.openstack.org/api/openstack-object-storage/1.0/content/GET_showContainerDetails__v1__account___container__storage_container_services.html
source File: file:/home/jenkins/workspace/object-api-tox-doc-publishdocs/openstack-object-storage-dev/ch_object-api-operations.xml
xml:id: GET_showContainerDetails__v1__account___container__storage_container_services

[Tom Fifield (fifieldt)]

That seems reasonable. Thanks for the report!

[Anastasia Martynova (anastasia-martynova)]

@Martin Geisler, I agree this link seems to be redundant, but it serves one important purpose: it instantly shows a developer that Swift API follows HTTP 1.1 protocol.

Can you please advise, if perhaps one of the two solutions can work for the bug?:

a) Rephrase the sentence into something like "Swift API implements HTTP 1.1 protocol" on each page of object storage reference

or

b) Add such sentence to "Overview" section of object storage reference

If this indication already exists somewhere, please let me know and I will remove those "see definition" parts from manuals.

[Martin Geisler (mgeisler)]

Hi Anastasia. Personally, I don't need to be reminded on every page that this *web* service speaks the normal protocol used for web services :-)

So I would leave it out on the individual pages. Having a sentence in the overview section sounds fine. Something like this "The Swift API is HTTP 1.1, which means that you can use cache control headers such as If-Modified-Since in your queries." As a developer, that is useful information.

Simply saying that the server speaks HTTP 1.1 is less useful since it's unclear which features of HTTP 1.1 we're talking about: it seems we're talking about caching mostly -- but what about other HTTP 1.1 features such a pipelining?

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/102668

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/102669

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/102669
Committed: https://git.openstack.org/cgit/openstack/object-api/commit/?id=f6c48e0ec6de1db3053026da729c1099f7e67c4c
Submitter: Jenkins
Branch: master

commit f6c48e0ec6de1db3053026da729c1099f7e67c4c
Author: Anastasia Martynova <email address hidden>
Date: Wed Jun 25 16:01:38 2014 -0700

    Removes irrelevant links to HTTP definition

    Removes sentence "For a complete description of HTTP 1.1 header definitions, see Header Field Definitions" from several pages on ch02,
    object-api reference.

    Change-Id: If37530f2d4f36523fd55ea170debacdf01940c1a
    Partial-bug: #1332008

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/102668
Committed: https://git.openstack.org/cgit/openstack/api-site/commit/?id=f43afb0273da14a0a68c7ef877595b7025ee57f0
Submitter: Jenkins
Branch: master

commit f43afb0273da14a0a68c7ef877595b7025ee57f0
Author: Anastasia Martynova <email address hidden>
Date: Wed Jun 25 14:45:34 2014 -0700

    Removes irrelevant links to HTTP definition.

    Removes sentence "For a complete description of HTTP 1.1 header definitions, see Header Field Definitions." from several pages on ch02, object-api, stored in wadl files

    Change-Id: If574799dddbd79d49984041e9d51603feae2d669
    Closes-bug: #1332008