January 5, 2016 at 6:06 pm #6709
I am just curious as to the rationale behind how the ForgeRock Common REST (CREST) API was derived, and why it does not conform to the more traditional REST use of HTTP verbs. An existing forum or blog post, wiki article or documentation link would be fine (I see in the OpenAM Developers manual that this is a conscious divergence, but I’d like to understand why this route was chosen).
My curiosity was most recently peaked by performing token validation, which is a query operation but (a) uses a POST and (b) expects that the Content-Type header be set to “application/json” even though there is no data expected to be sent by the client to the API. This seems to run fairly counter to behaviors I’ve come to expect from most REST APIs.
Thank you very much in advance!March 14, 2016 at 6:31 pm #8540James PhillpottsModerator
Thanks for the interesting question :)
In mapping the CREST operations to HTTP verbs, the sections of the HTTP 1.1 specification that deal with method definitions are important. In particular the sections about safe methods and idempotent methods are important.
The spec states that the GET method must be both safe and idempotent. However, the action class of CREST operations, of which session validation is one, are not guaranteed to be idempotent. Indeed, in the case of session validation, the idle time of the session may be reset by the operation, so it is definitely not a safe or idempotent operation.
That said, there are still issues with some of the mappings that we are in the process of trying to resolve. We have already recently changed the create operation to be a plain POST without an
?_action=createparameter. We hope to address the issue with non-child query operations that are generally represented as POST actions – if they are safe, idempotent operations they really shouldn’t be represented as such. Watch this space!
I hope this helps. If you have any other observations about the HTTP mappings, we’re definitely keen to hear more opinions.May 10, 2016 at 5:48 pm #10410
Thank you very much for the additional insight James. It was not apparent from the documentation that query operations for tokens or sessions might have the side effect of expiring / invalidating the token or session. Is this also a side effect of other CREST API calls, or is it only triggered by the token / session queries?October 27, 2016 at 8:32 pm #13956
I went back an re-read the section on safe methods, and it seems like the change of session state would be permitted, if that is not the purpose of the call (e.g., the purpose of the query method from the client perspective is not to change session state, but to query the current status of the session).
This definition of safe methods does not prevent an implementation
from including behavior that is potentially harmful, that is not
entirely read-only, or that causes side effects while invoking a safe
method. What is important, however, is that the client did not
request that additional behavior and cannot be held accountable for
it. For example, most servers append request information to access
log files at the completion of every response, regardless of the
method, and that is considered safe even though the log storage might
become full and crash the server. Likewise, a safe request initiated
by selecting an advertisement on the Web will often have the side
effect of charging an advertising account.
The method would certainly idempotent, in that the same effect occurs regardless of how many times it is called for a given resource in a given state. Just food for thought.July 30, 2019 at 11:16 pm #26144AMDeveloperParticipant
@jamesphillpotts hi James,
You mentioned on this forum that
We have already recently changed the create operation to be a plain POST without an ?_action=create parameter.
However, in 6.5 documentation, I am seeing everywhere that we are still using create operation with _action
If I am not missing anything, would you please help me understand the rationale behind it.
Is it because we want to differentiate HTTP POST’s overloaded usage i.e., create and update ?
Thanks.August 6, 2019 at 1:29 pm #26171James PhillpottsModerator
Yes, I believe the docs still refer to
_action=createas that works for all versions. The rationale behind it was to conform to the de facto standard in the industry for RESTful create operations using the POST HTTP verb, and to better align with the IETF definition:
For example, POST is used for the following
functions (among others):
o Creating a new resource that has yet to be identified by the
origin server; and
You must be logged in to reply to this topic.