RESTful API Design best practice for request metadata (session id etc)?

Question

When designing a REST API, what is the best practice for passing metadata you require for statistics and logging, but which doesn't change the response from the server?

For example, if I have a service to find the nearest public toilet, I may want to know whether the user's location was determined by GPS. Or if an end user's request passes through several systems, I may want to pass a request ID for debugging.

As I understand it the options are:

Query parameters

• Like the 'sensor' parameter on the Google Maps APIs.
• Right because it lets users explore the API with a regular web browser.
• Right because it's simpler for clients who find it hard to send custom HTTP headers.
• Wrong because filter parameters are only for filtering, sorting & searching.
• Wrong because if the resource doesn't change, why should the URL?

HTTP headers

• Like authentication is often done
• Right because it's the normal place for request metadata that doesn't change the server's response
• Right because, for POST/PUT requests, it avoids having both query parameters and a request body.
• Wrong because you can't set headers when you explore an API with your web browser.
• Wrong because complexity should be avoided, and URL+Header is a more complicated API than URL alone.

Which is the right choice if the metadata is allowed to be absent?

Is the answer different if the metadata must be present, though it's value otherwise doesn't change the server's response?

Answer 1

HTTP Headers is the right answer. That's what they are there for.

The web browser as a debugger is not a particularly valid considering how many other viable options exist for testing web apis. Stuff like Postman, Dev HttpClient, Fiddler, Runscope are all decent ways to test APIs.