Tagged: ,

This topic has 5 replies, 3 voices, and was last updated 3 years, 1 month ago by James Phillpotts.

  • Author
  • #6709
     Gregory Wright

    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!


    Hi Gregory,

    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=create parameter. 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.

     Gregory Wright

    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?

     Gregory Wright

    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.


    @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 ?



    Yes, I believe the docs still refer to _action=create as 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

Viewing 6 posts - 1 through 6 (of 6 total)

You must be logged in to reply to this topic.

©2022 ForgeRock - we provide an identity and access platform to secure every online relationship for the enterprise market, educational sector and even entire countries. Click to view our privacy policy and terms of use.

Log in with your credentials

Forgot your details?