title: OpenAM RESTful API changes link: https://onemoretech.wordpress.com/2015/06/10/openam-restful-api-changes/ author: phil2nc description: post_id: 9781 created: 2015/06/10 13:41:46 created_gmt: 2015/06/10 17:41:46 comment_status: closed post_name: openam-restful-api-changes status: publish post_type: post

OpenAM RESTful API changes

For those who run OpenAM in production this is probably going to be old news, for the rest of us maybe not so much. As of OpenAM 11 (released in October, 2014) the existing RESTful API is now referred to as "legacy" with a status of "deprecated", to make room for a totally reworked version labeled "native". More fun talk after the fold.

Although "deprecated" means the legacy API could potentially disappear from OpenAM in an upcoming version, as of the latest OpenAM 13 development snapshot (nightly) it is still being supported. The Developer's Guide for latest subscription release, OpenAM 11.0.0 (released October 2014, last updated for v11.0.3 in March, 2015), includes documentation on how to use both the new and legacy APIs in a chapter entitled Using RESTful Web Services.

This material isn't substantially changed in the next stable release, OpenAM 12.0.0 (released and last updated in December, 2014). That's good news, I think, because from what I've been able to gather in the 24 hours since I discovered this, the new API doesn't seem to have all the features of the old. In fact I'm a little concerned about the practicality of implementing the new API for a couple of reasons:

First, there's apparently a bug in the logout method that causes it to burp back an "unauthorized" error. I experienced this myself while trying things out so I could explain the changes to others. Second, version 13's "REST Resource v2" changes the urls for the "application" and "policies" endpoints, which if you'd already started coding to v1 could be frustrating. This is of course a challenge for system architects like myself who have to make sure that my company's apps don't break the next time the identity system gets upgraded for security purposes.

So although I'm recommending to all my developers that they begin working on adapting their apps that use OpenAM REST to the new API, I'm also confiding in them that they might want to make sure they remain prepared to use the legacy API in the event the new one isn't deemed stable enough. Note that I've just updated an earlier article reviewing the original (now "legacy") API to correct the examples so they explicitly perform requests as a "POST". Although using "GET" worked under OpenAM 9.5.4, that was apparently only due to a bug that's since been fixed. Web security best practices would dictate that "POST" should always be used when conducting identity operations in any event (as should HTTPS).

NOTES: Check out this article posted by the lead OpenAM developer at the time the new API was in testing.

Copyright 2004-2019 Phil Lembo