Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify Request Method Override Documentation #9958

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Clarify Request Method Override Documentation #9958

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 11 additions & 4 deletions doc/12-icinga2-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -355,9 +355,15 @@ Example as JSON object:

### Request Method Override <a id="icinga2-api-requests-method-override"></a>

`GET` requests do not allow you to send a request body. In case you cannot pass everything as URL
parameters (e.g. complex filters or JSON-encoded dictionaries) you can use the `X-HTTP-Method-Override`
header. This comes in handy when you are using HTTP proxies disallowing `PUT` or `DELETE` requests too.
Following the HTTP specification, `GET` requests do not have a [semantic for content sent in the request body](https://www.rfc-editor.org/rfc/rfc9110#section-9.3.1-6).
In other words, sending additional content within a `GET` request might work, but some web server implementations are going to reject this.
The Icinga 2 API supports this behavior and even makes use of this, e.g., for complex filters or JSON-encoded dictionaries.

However, when not connecting directly to the Icinga 2 API, but going through some middleware or proxy server, either the whole request or the content might get dropped.
In this case, Icinga 2 supports the `X-HTTP-Method-Override` HTTP header for method overriding within `POST` requests.
This also comes in handy when using HTTP proxies disallowing `PUT` or `DELETE` requests.

To avoid these difficult to debug errors, request method overriding is used in all further examples, even if not strictly necessary.

Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:

Expand Down Expand Up @@ -519,7 +525,8 @@ curl -k -s -S -i -u 'root:icinga' -H 'Accept: application/json' \
```

We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) here because
the HTTP specification does not allow message bodies for GET requests.
the HTTP specification is quite vague regarding GET requests with a request body
and middle boxes might drop those requests.

The `filters_vars` attribute can only be used inside the request body, but not as
a URL parameter because there is no way to specify a dictionary in a URL.
Expand Down