CODEWITHSUNDEEP
rest
RailRhoad
RailRhoad

Reputation: 2128

REST Best Practice GET with context parameters

We have a series of REST services that pull resources by identifier but we've been recently tasked with passing disclosure parameters to save with audit.

What use to be... 

GET entity/{id}

now turns into something like...

GET entity/{id}?requestName=&requestingOrganization=&reasonForUse=&verificationMethod=&otherAuditDisclosureProperties....

The state of entity does not change and is still idempotent however we must audit the additional information with each call in order to provide it.

First thought was to construct a body instead but that did not seem proper for a GET. This is the second approach using query parameters which have no intention of querying/filtering. These additional parameters are truly context information captured at the point of request. These are the equivalent of SAML attributes within a SOAP call that live outside of the SOAP body (which makes me think as possible header attributes).

Also note, that this information is relayed so the authentication token provided is for the service user calling in and not the actual identity of the context. The identity of the original caller is implicitly trusted in the trust framework surrounding.

How would you define this verb/path?

Upvotes: 3

Views: 844

Answers (2)

Walter Palladino
Walter Palladino

Reputation: 479

I agree with Daniel Cerecedo. The proper way is to add the information as part of your Request Header. A general information can be found at: https://www.w3.org/Protocols/HTTP/HTRQ_Headers.html The implementation will depends on your programming language.

Upvotes: 0

Daniel Cerecedo
Daniel Cerecedo

Reputation: 6207

Maybe a custom header: vnd.mycompany.myheader; where you put all the params you need in some parseable format: name1=value1; name2=value2. You take the waste out of the query string.

The off-topic response

I cannot imagine an scenario where you are asking the user of an API for such subjective information, that requires a lot of effort to provide (as it changes per request) and provides no value to the client. It is only for your internal use. The most probable result is clients hard coding those values and repeating them over in all requests.

If the client is internal you may be looking for ways to correlate requests that span multiple services, like Sleuth, which will let you understand why clients are using your API.

If the client is external, think of making surveys and personal interviews with developers. I'd also suggest that you first nurture your API community to reach those people and understand how and why they use your API.

Upvotes: 1

Related Questions