Add parameters for new http headers in hefquin-api.yml

[KentThang]

Second part of #722.

I'm not familiar with .yml files so please take an extra look! I added references to the new parameters (headers) to every endpoint. Maybe that isn't necessary? If it should be added to every endpoint, it should be possible to add the references at the path level, to avoid repetition.

[hartig]

Same comments on this PR as for PR #724.

Having said that, we probably don't want to have particularly long descriptions in this case here. Maybe you can add links to the description that you will create when addressing the comments for PR #724 ?

[hartig]

@keski can you please take a look at this PR to confirm that it is formally correct (in terms of the format of the file).

[hartig]

@KentThang The comments that my earlier review for this PR refers to are #724 (comment) and #724 (comment) The same changes that you have done for these comments in PR #724 can be done here as well.

@keski can you please take a look at this PR as well; we need someone to confirm that the changes in this PR are formally correct (in terms of the format of the file).

[KentThang]

Yes! I haven't forgotten about this, I've just been occupied with other issues. Will resolve this now so @keski can take a look at it.

[KentThang]

Do you think any of these descriptions are too long and if so, do I just add a link to this https://liusemweb.github.io/HeFQUIN/doc/cli.html ?

[hartig]

Do you think any of these descriptions are too long and if so, do I just add a link to this https://liusemweb.github.io/HeFQUIN/doc/cli.html ?

Not to ...cli.html but, maybe, to https://liusemweb.github.io/HeFQUIN/doc/hefquin_service.html -- That's where the more detailed description of each of these headers is. But if you include links, then these should use HTML anchors within hefquin_service.html to link directly to the description of the respective header.

@keski would it be possible to include such links in the description: fields of the yml file?

@KentThang another thing that I notice now: while the yml file specifies the possible values for these headers, the corresponding descriptions in hefquin_service.html do not say anything about it. In other words, just based on the description in hefquin_service.html, I wouldn't know how exactly to include these headers in my requests to HeFQUIN service. In fact, the individual descriptions in hefquin_service.html do not even talk about "this header" but about "this argument", which is confusing. Can you please fix these two issues in hefquin_service.html in a separate PR.

[keski]

@keski would it be possible to include such links in the description: fields of the yml file?

Yes, this is possible and supported by OpenAPI. The format is similar to markdown, e.g.:

description: |
    My parameter.

    See the [info about parameter](https://example.com/my-parameter)

[KentThang]

I have now added links to descriptions for the cache-related headers which I thought was a little lengthy. Let me know if you still think the other ones are too long and I can shorten them / add link to the docs.

[hartig]

The links should not just point generally to hefquin_service.html but, instead, directly to the corresponding description of the particular header within that HTML file. To this end, you need to make the add anchors to the individual descriptions in hefquin_service.html. For instance, turn:

<li><code>X-HeFQUIN-Skip-Execution</code> ...

into:

<li id="X-HeFQUIN-Skip-Execution"><code>X-HeFQUIN-Skip-Execution</code> ...

and then you can link directly to it using the URL https://liusemweb.github.io/HeFQUIN/doc/hefquin_service.html#X-HeFQUIN-Skip-Execution

Another thing: the descriptions of the printing-related headers should also include links to their corresponding description in hefquin_service.html because there is more detail for them as well (e.g., which JSON field is used for them in the JSON response).

[KentThang]

Latest commit here and in #751 should resolve your latest comment.

[hartig]

Thanks!