1. Administration and Configuration Guide
  2. Generic Configurations
  3. Using REST APIs for User Management from Third-Party IDMs
  4. Understanding REST API Specifications

Understanding REST API Specifications

Note:

Prefix http://<Webserverip>:<servletport>/<context> to the values in the URL column.

For example, /rest-api/idm/service/create/user must be http://<Webserverip>:<servletport>/<context>/rest-api/idm/service/create/user.

The following table provides details for the REST APIs:

Table 12-4 REST API specifications

No Requirement URL Method Type Request Sample Request JSON Comments
1 Create User /rest-api/idm/service/create/user POST JSON

{

"attributes": {

"user_id": "user_id",

"user_name": "user_name",

"user_password": "password",

"user_start_date": "start_date",

"user_end_date": "End_date",

"user_is_authorized": true(/false),

"user_is_enabled": true(/false),

"user_logon_holiday": true(/false)

"smsauthonly": true(/false)

}

}

All fields are mandatory.

The Date format is mm/dd/yyyy.

If user_is_authorized is set to true, then the User is authorized during User creation.

If smsauthonly is set to true, then the User is authenticated only using the SMS Authentication type. If it is set to false, then the User can be authenticated using the SMS, LDAP and SSO authentication types. However, the smsauthonly configuration feature is available in the OFS AAI Release 8.1.1.1 and later versions.
2 Update User /rest-api/idm/service/update/user POST JSON

{

"attributes": {

"user_id": "user_id",

"user_name": "user_name",

"user_password": "password",

"user_start_date": "start_date",

"user_end_date": "End_date",

"user_is_authorized": true(/false),

"user_is_enabled": true(/false),

"user_logon_holiday": true(/false)

"smsauthonly": true(/false)

}

}

All fields are mandatory.

The Date format is mm/dd/yyyy.

If user_is_authorized is set to true, then the User is authorized during User creation.

If smsauthonly is set to true, then the User is authenticated only using the SMS Authentication type. If it is set to false, then the User can be authenticated using the SMS, LDAP and SSO authentication types. However, the smsauthonly configuration feature is available in the OFS AAI Release 8.1.1.1 and later versions.
3 Delete User /rest-api/idm/service/delete/user POST TEXT USERID The User ID is mandatory.
4 Authorize User /rest-api/idm/service/authorize/user POST TEXT USERID The User ID is mandatory.
5 Force User Delete rest-api/idm/service/delete/user/force POST TEXT USERID

The User ID is mandatory.

NOTE: This is applicable only after applying 8122 ML
6 Reinstate User /rest-api/idm/service/reinstate/user POST TEXT USERID The User ID is mandatory.
7 Map User to Group /rest-api/idm/service/map/groupmembers POST JSON

{

"user_id": "user_id",

"group": [

{

"group_id": "group_id",

"group_name": "groupname"

},

...

]

}

 The mapping of the User ID to Groups.
8 Unmap User from Group /rest-api/idm/service/unmap/groupmembers POST JSON

{

"user_id": "user_id",

"group": [

{

"group_id": "group_id",

"group_name": "groupname"

},

...

]

}

 The unmapping of the User IDs from Groups.
9 User Status Report /rest-api/v1/user/status?userId=<USERID>&userName=<USERNAME>&idledays=<Number of days idle>&gsUserID=<Logged-in user>&loggedIp=<IP Address>&enable=<Y/N>&delete=<Y/N>&loggedIn=<Y/N> GET -

For example:

https://<HOST_NAME:PORT>/<CONTEXTNAME>/rest-api/v1/user/status?userId=exampleUserID&userName=exampleUserName &idledays=&gsUserID=SYSADMN&loggedIp=<192.0.2.1>&enable=Y&delete=N&loggedIn=Y

The JSON request displays the Report for the deleted, disabled, currently logged in, and idle Users.

Note:

The Get Response populates additional fields in v8.1.2.0.0+ on applying the 33150367 One-off Patch. See the Appendix B – Additional Information in REST APIs for User Status and User Access Reports Section for more details.

  • If you do not enter the values for the gsUserID and loggedIp attributes in this API, the transaction is not recorded in audit.
  • If you do not enter the values for the userId and userName attributes in this API, the records for all the users is displayed.
  • userID is the OFSAA identifier of the User for whom the report is to be generated.
  • userName is the OFSAA login name for the above User ID.
  • idledays is the number of days (INTEGER) the user has not logged into the system.
  • gsUserID is the User ID of the user logged in and accessing the system.
  • loggedIP is the IPv4 address of the workstation from where the RESTful API IP is invoked. An alternative is to configure it to the loopback address 127.0.0.1.
  • enable is the flag to detemine if the user is enabled or disabled in the system. The valid values are Y for yes and N for no.
  • delete is the flag to detemine if the user is deleted in the system. The valid values are Y for yes and N for no.
  • loggedIn is the flag to detemine if the user is currently logged into the system. The valid values are Y for yes and N for no.
  • Oracle recommends that you copy and paste the URL and modify the placeholders.
10 User Attribute Report /rest-api/v1/user/attributes?userId=<USERID>&userName=<USERNAME>&gsUserID=<Logged-in User>&loggedIp=<IP Address> GET -

For example:

https://<HOST_NAME:PORT>/<CONTEXTNAME>/rest-api/v1/user/attributes?userId=exampleUserID&userName=exampleUserName&gsUserID=SYSADMN&loggedIp=<192.0.2.1>

The JSON request displays the Report for the various User attributes.

Note:

  • If you do not enter the values for the gsUserID and loggedIp attributes in this API, the transaction is not recorded in audit.
  • If you do not enter the values for the userId and userName attributes in this API, the records for all the users is displayed.
  • userID is the OFSAA identifier of the User for whom the report is to be generated.
  • userName is the OFSAA login name for the above User ID.
  • gsUserID is the User ID of the user logged in and accessing the system.
  • loggedIP is the IPv4 address of the workstation from where the RESTful API IP is invoked. An alternative is to configure it to the loopback address 127.0.0.1.
  • Oracle recommends that you copy the URL and modify the placeholders.
11 User Admin Activity Report /rest-api/v1/user/useradminactivity?userId=<USERID>&userName=<USERNAME>&startdate=<mm/dd/yyyy>&enddate=<mm/dd/yyyy>&gsUserID=<Logged-in User>&loggedIp=<IP Address> GET -

For example:

https://<HOST_NAME:PORT>/<CONTEXTNAME>/rest-api/v1/user/useradminactivity?userId=exampleUserID&userName=exampleUserName&startdate=01/01/2020&enddate=12/31/2020&gsUserID=SYSADMN&loggedIp=<192.0.2.1>

The JSON request displays the Report for the various activities of the User.

Note:

  • The values for the startdate and enddate atributes in this API are required.
  • If you do not enter the values for the userId and userName attributes in this API, the records for all the users is displayed.
  • If you do not enter the values for the gsUserID and loggedIp attributes in this API, the transaction is not recorded in audit.
  • userID is the OFSAA identifier of the User for whom the report is to be generated.
  • userName is the OFSAA login name for the above User ID.
  • startdate is the date from which the report is to be considered. The Date format is mm/dd/yyyy.
  • enddate is the end date to be considered for the report. The Date format is mm/dd/yyyy.
  • gsUserID is the User ID of the user logged in and accessing the system.
  • loggedIP is the IPv4 address of the workstation from where the RESTful API IP is invoked. An alternative is to configure it to the loopback address 127.0.0.1.
  • Oracle recommends that you copy the URL and modify the placeholders.
12 User Access Report /rest-api/v1/user/useraccess?userId=<USERID>&userName=<USERNAME>&gsUserID=<Logged-in User>&loggedIp=<IP Address> GET -

For example:

https://<HOST_NAME:PORT>/<CONTEXTNAME>/rest-api/v1/user/useraccess?userId=exampleUserID&userName=exampleUserName&gsUserID=SYSADMN&loggedIp=<192.0.2.1>

The JSON request displays the Report for User Access Rights.

Note:

The Get Response populates additional fields in v8.1.2.0.0+ on applying the 33150367 One-off Patch. See the Appendix B – Additional Information in REST APIs for User Status and User Access Reports Section for more details.

  • If you do not enter the values for the gsUserID and loggedIp attributes in this API, the transaction is not recorded in audit.
  • If you do not enter the values for the userId and userName attributes in this API, the records for all the users is displayed.
  • userID is the OFSAA identifier of the User for whom the report is to be generated.
  • userName is the OFSAA login name for the above User ID.
  • gsUserID is the User ID of the user logged in and accessing the system.
  • loggedIP is the IPv4 address of the workstation from where the RESTful API IP is invoked. An alternative is to configure it to the loopback address 127.0.0.1.
  • Oracle recommends that you copy the URL and modify the placeholders.
13 Audit Trail Report /rest-api/v1/audit/summary POST JSON

{

"userId":"<User Id>",

"fromdate":"<Date>",

"todate":"<Date>",

"action":"<add/copy/delete/authorize and other actions>",

"strlocale": "en_US",

"msgsearchfld":"",

"loggedIP":"<IP Address>",

"gsUsrID":"<Logged-in User Id>"

}

The JSON request displays the Report for Audit Trail.

Note:

  • The values for the fromdate, todate, and strlocale attributes in this API are required.
  • If you do not enter the values for the gsUserID and loggedIp attributes in this API, the transaction is not recorded in audit.
  • If you do not enter the value for the userId attribute in this API, the records for all the users is displayed
  • userID is the OFSAA identifier of the User for whom the report is to be generated.
  • userName is the OFSAA login name for the above User ID.
  • fromdate is the date from which the report is to be considered. The Date format is mm/dd/yyyy.
  • todate is the end date to be considered for the report. The Date format is mm/dd/yyyy.
  • action is the type of method. The valid options are as follows:

Note: If you do not enter any value for this attribute, all records for the actions is displayed.

Displays all actions performed by the selected user.

When the audit trail report is generated the details of the associated activity/data field and the application rule IDs of the PMF process is also added as the Action details for all the displayed actions.

  • Add

Displays add events performed by the selected user.

  • Advanced

Displays advanced events performed by the selected user.

  • Authorize

Displays authorization performed by the selected user.

  • Archive

Displays archive actions performed by the selected user.

  • Compare

Displays compare actions performed by the selected user.

  • Copy

Displays copy events performed by the selected user.

  • Disable

Displays any disable actions performed by the selected user.

  • Download

Displays downloads done by the selected user.

  • Edit

Displays any edits done by the selected user.

  • Enable

Displays any enable actions done by the selected user.

  • Execute

Displays execute actions performed by the selected user.

  • Export

Displays export events performed by the selected user.

  • Generate

Displays generate events performed by the selected user.

  • Ignore access

Displays ignore access events performed by the selected user.

  • Ignore lock

Displays ignore lock events performed by the selected user.

  • Import

Displays import events performed by the selected user.

  • Latest

Displays the latest events performed by the selected user.

  • Link

Displays any link events performed by the selected user.

  • Lock

Displays any lock events linked to the selected user.

  • Login

Displays login events performed by the selected user.

  • Logout

Displays logout events performed by the selected user.

  • Publish

Displays publish events performed by the selected user.

  • Purge

Displays purge events performed by the selected user.

  • Reject

Displays reject events performed by the selected user.

  • Delete

Displays delete events performed by the selected user.

  • Restore

Displays restore events performed by the selected user.

  • Review

Displays review events performed by the selected user.

  • Revoke

Displays revoke events performed by the selected user.

  • Submit

Displays submit events performed by the selected user.

  • Summary

Displays summary modifications performed by the selected user.

  • Trace

Displays trace events performed by the selected user.

  • Upload

Displays uploads performed by the selected user.

  • Validate

Displays validate events performed by the selected user.

  • View

Displays view events performed by the selected user.

  • strlocale is the language code string such as en_US.
  • msgsearchfld is the search field string. This value is optional.
  • loggedIP is the IPv4 address of the workstation from where the RESTful API IP is invoked. An alternative is to configure it to the loopback address 127.0.0.1.
  • gsUserID is the User ID of the user logged in and accessing the system.
  • Oracle recommends that you copy the URL and modify the placeholders.
NOTE:
  • The below APIs are applicable on 8.1.2.3.0 after applying the 35322369 One-off Patch.
  • Apply the patch 35829211 to prevent creating AAI and related tables, when you are creating INFODOM.
14 Create Application /rest-api/v1/app/create POST JSON

{

"appId": "application id",

"appName": "application name",

"appDesc": "application desc",

"infodomId": "Infodom name",

"enabled": true/false, "userLocale":"locale (en_US)"

}

All fields are mandatory.

If Enabled is set to true then created application will be enabled else it will be disabled.
15 Delete Application /rest-api/v1/app/ delete/app_Id DELETE Path param Url Params are used so sample request will be as follows: rest-api/v1/app/app_id app id is mandatory.
16 Create Infodom /rest-api/v1/infodom/create POST JSON

{

"appLogPath": "/scratch/test8123/ftpshare/ PAERTHTESTINFO /logs",

"dbLogPath": "/scratch/test8123/ftpshare/ PAERTHTESTINFO /logs",

"infodomName": "PAERTHTESTINFO",

"infodomDesc": "PAERTHTESTINFO DESC",

"authRSNRequired": false,

"infodomTypeStaging": true,

"dbName":"testparth",

"dbServer":"100.76.146.194", --FIC_HOME IP

"olapServer":"127.0.0.1",

"olapType":"ESSBASE",

"scriptRequired" : false --default is true [which creates AAI related tables]

} 		 
17 Delete Infodom /rest-api/v1/infodom/delete/infodom_name DELETE Path param Url Params are used so sample request will be as follows: rest-api/v1/app/infodom_name Infodom name is mandatory.
18 Create segment /rest-api/v1/segment /create POST JSON

{

"segmentCode":"segment_code",

"segmentName":"segment_name",

"segmentDesc":"segment_desc",

"segmentType":"segment_type",

"dsnID":"infodom_id",

"ownerCode":"user_id"

}

All fields are mandatory.

Three types of segmentType (PUBLIC, PRIVATE, SHARED)

ownerCode is user id if you have selected segmentType as private.
19 Authorize role group /rest-api/v1/group/role/authorize?operation=map&auth=A POST JSON

{

"groupid":"BUSINESSADMIN",

"rolecodes" : ["QLOCAUTHRL","QLOCVIEWRL"]

} 		operation=map/unmap[based on roles are mapped or unmapped auth=A/R [A:authorize, R:reject]
20 Authorize domain group /rest-api/v1/group/domain/authorize?operation=map&auth=A POST JSON

{

"groupid":"IDENTITYMGMTAUTH",

"domainnames" : ["PARTHTESTINFO-PTFLD","PARTHTESTINFO-PARFLD"]

} 		operation=map/unmap[based on domains are mapped or unmapped] auth=A/R [A:authorize, R:reject]
21 Create Database Details /rest-api/v1/ database-details/create POST JSON

{

"dbServer":"100.76.146.194",

"dbName":"aaipatest",

"dbSchemaName":"aaiptest",

"dbDateFormat":"mm-dd-yyyy",

"authAliasName":"aaipatest",

"authAliasUserName":"aaipatest",

"authAliasPassword":"aaipatest",

"dataSourceString":"SMSOCI19PDB", "jdbcConnString":"jdbc:oracle:thin:@100.76.146.194:1521/SMSOCI19PDB",

For Wallet:

jdbc:oracle:thin:/@july25_als

where july25_als is the alias created for new schema user created.

"jndiName":"AAIPATESTINFO"

} 		All Fields Are required.