Solutions
Archived

REST API calls fail after upgrading to OpenAM 13.x

Last updated Jan 5, 2021

The purpose of this article is to provide assistance if your REST API calls (that worked previously) fail after upgrading to OpenAM 13.x. This includes requests made indirectly; for example, when you create a REST STS instance in the OpenAM console.


1 reader recommends this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Symptoms

The REST call, or OpenAM functionality that has an underlying REST request, fails after upgrading to OpenAM 13.x. The same behavior worked in older versions.

Example failed request 

The following example shows a REST call and the possible failed responses:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Content-Type: application/json" --data '{"currentpassword":"changeit","userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

Which can result in:

{"code":501,"reason":"Not Implemented","message":"Actions are not supported for resource instances"}

Or:

{"code":404,"reason":"Not Found","message":"User not found"}

Example failed functionality with underlying REST request

When adding a REST STS instance in the OpenAM console, you may receive the following error:

HTTP Status 500 - AMSetupFilter.doFilter

Recent Changes

Upgraded to OpenAM 13.x.

Causes

The resource version associated with the REST request is incompatible with the endpoint being called and OpenAM release combination.  

REST API features have version numbers to allow for compatibility between releases. The version number of a feature increases when a non-backwards-compatible change is introduced that affects clients making use of the feature. Versioning is provided for the resource and protocol elements. See OpenAM Developer's Guide › REST API Versioning for further information on versioning.

OpenAM supports protocol version 1.0; supported resource versions vary according to the endpoint and the release you are using. You should check Supported resource Versions for further information.

Solution

This issue can be resolved by ensuring you use a resource version that is appropriate to the endpoint and OpenAM release you are using.

You can configure a global setting to determine version compatibility or specify the versions in your REST request.

Global setting

You can configure the global setting using either the OpenAM console or ssoadm:

  • OpenAM 13.5 console: navigate to: Configure > Global Services > REST APIs > Default Version and select the appropriate option. 
  • OpenAM 13 console: navigate to: Configuration > Global > REST APIs > Default Version and select the appropriate option. 
  • ssoadm: enter the following command: $ ./ssoadm set-attr-defs -s RestApisService -t Global -u [adminID] -f [passwordfile] -a openam-rest-apis-default-version=[version] replacing [adminID], [passwordfile] and [version] with appropriate values, where [version] is LATEST, OLDEST or NONE.

The options available are:

  • LATEST: The latest available supported version of the API is used. This is the preset default for new installations of OpenAM.
  • OLDEST: The oldest available supported version of the API is used. This is the preset default for upgraded OpenAM instances.
  • NONE: If a version is not specified in the request, it will not be defaulted. 
Caution

If you select NONE for the global setting, you must always specify the version in the REST request. If the version is not specified the request will not be handled and will result in a 400 Bad Request error.

You can include the Accept-API-Version header in your REST call to specify the versions. For example, to include resource version 2.0 you would include the following header:

"Accept-API-Version: resource=2.0"

For example:

$ curl --request POST --header "iPlanetDirectoryPro: AQIC5wM2LY4Sfcxs...EwNDU2NjE0*" --header "Accept-API-Version: resource=2.0" --header "Content-Type: application/json" --data '{"currentpassword":"changeit", "userpassword":"newpassword"}' http://openam.example.com:8080/openam/json/users/user.0?_action=changePassword

 See OpenAM Developer's Guide › Specifying an Explicit REST API Version for further information.

See Also

FAQ: REST API in AM

OpenAM Developer's Guide › REST API Versioning

OpenAM Administration Guide › Configuring REST APIs

Related Training

N/A

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.