Overview

rest methods determine the http method for manipulating the resources defined in the service operation the kind of operations available include those predefined by the http verbs get, post, put, delete and so on the response may confirm that some alteration has been made to the stored resource, and it may provide hypertext links to other related resources or collections of resources by making use of a stateless protocol and standard operations, rest systems aim for fast performance, reliability, and the ability to grow, by re using components that can be managed and updated without affecting the system as a whole, even while it is running rest api support for ics involves only configuration apis also, ics supports only the get, post, put and delete apis the valid and supported values are described in the following valid and supported values table http verb definition delete delete an existing resource get retrieve a representation of a resource post create a new resource put create a new resource to a new url or modify an existing resource to an existing url the error codes supported are described in the following error codes supported table http verb definition 200 ok requesting for resource information successful using get resource update successful using put 201 created resource creation successful using post 204 no content deletion of resource successful with no body even put, post may return 204 if no errors or warnings seen 400 – bad request any request (get/put/post/delete, and so on) is invalid example incorrect json format 401 – unauthorized any rest call with invalid credentials 403 – forbidden rest call with valid credentials but no permission 404 – not found requested resource in uri does not exist 422 – unprocessable entity any validation/referential integrity errors that would result in failure of put/post/delete request 500 server error when ics rest server is not responding url encoding a url can be from a limited set of characters belonging to the us ascii character set characters outside these character set are not allowed to be placed directly within urls, but their encoded value preceded by % can be used in the urls the following table demonstrates url encoding character url encoding (utf 8) \<space> %20 # %23 $ %24 % %25 & %26 %2a / %2f @ %40 \ %5c enclose non ascii characters in single quotes (') or double quotes (") example to get active session details of user “admin user” curl k u \<api key> 'https //\<ics ip>/api/v1/system/active users?name=admin%20user' to get active session details of user “admin\@user” curl k u \<api key> 'https //\<ics ip>/api/v1/system/active users?name=admin%40user' for more details, refer https //www urlencoder io/learn/ https //www urlencoder io/learn/ authentication for rest apis basic authentication using the http authorization header is used to authenticate username/password on the administrators auth server it is expected that the user is already configured in the administrators auth server on a successful login, a random token (api key) is generated once and sent back as a json response further access to apis can use this api key value as username and password as empty in their authorization header for access a new random api key is generated on a successful login the user can continue to use this key till the administrator enables/disables the user account ivanti recommends using api/v1/realm auth instead of api/v1/auth as it will not be supported from 22 7r2 1 release onwards update/modify your rest based scripts to make use of /api/v1/realm auth the generated api key is valid until the session timeout configured in admin roles and mapped to the admin realm after expiration, users can regenerate the api key using api/v1/realm auth realm based authentication (recommended) ivanti recommends realm based authentication instead of basic authentication using the https authorization header /api/v1/realm auth supports login via rest api on a particular admin realm with following mfa enabled saml or oauth not supported as primary auth supported authservers are administrators(local authserver) ad ldap radius totp primary authentication request post /api/v1/realm auth http/1 1 host xx xxx xxx xxx content type application/json authorization basic ywrtaw46zgfuyteymw== { "realm" "adminrealm" } response http/1 1 200 ok content type →application/json { "resume id" "c3rhdgvfyzg5nwm3ndqwnwf1zjnmnjuoywuz0gf1zthimjuxndq=" } secondary authentication request post /api/v1/realm auth http/1 1 host xx xxx xxx xxx content type application/json authorization basic ywrtaw46zgfuyteymw== { "resume id" "c3rhdgvfyzg5nwm3ndqwnwf1zjnmnjuoywuz0gf1zthimjuxndq=" } response http/1 1 200 ok content type →application/json { "api key" "njqzogu0n2i5mduymwzhzwm0nmzimtmxy2u3m2yym2q=" } authorization header for all future requests should perform basic auth using above api key value as username and password as empty request get /api/v1/configuration http/1 1 host xx xxx xxx xxx authorization basic cdvttwxjn1jrdtgxujjodnnztendwmhqmdvrzjbomk9ormvzzuxywdzhvt06 response http/1 1 200 ok content length →283 content type →application/json { "administrators" { "href" "/api/v1/configuration/administrators" } , "authentication" { "href" "/api/v1/configuration/authentication" } , "system" { "href" "/api/v1/configuration/system" } , "users" { "href" "/api/v1/configuration/users" } } sample get/post/put/delete request and responses in ics below is a sample of get/post/put/delete request and responses get api call fetch the specific user under local authentication server request get /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user/user0001 http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json response http/1 1 200 ok content length 309 content type application/json { "change password at signin" "false", "console access" "false", "enabled" "true", "fullname" "user0001", "one time use" "false", "password cleartext" "'xxxxxxx", "username" "user0001" } equivalent curl command command curl i u p9/h85ytemkdzvkgsmq4z77p6ya7alic42vh0f9cgaq= x get https //\<hostname>/api/v1/configuration/authentication/auth servers/auth server/system%20local/local/users/user/user0001 response http/1 1 200 ok content type application/json content length 303 { "change password at signin" "false", "console access" "false", "enabled" "true", "fullname" "user0001", "one time use" "false", "password cleartext" "'xxxxx", "username" "user0001" } post api call create user for existing local authentication server request post /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json { "change password at signin" "false", "console access" "false", "enabled" "true", "fullname" "user0001", "one time use" "false", "password cleartext" "'xxxxx", "username" "user0001" } response http/1 1 200 ok content length 122 content type application/json { "result" { "info" \[ { "message" "operation succeed without warning or error!" } ] } } equivalent curl command command curl i u hv5uaqowf5kuisvnuigeabol8fsczsk98zvwphywgke= x post https //\<hostname>/api/v1/configuration/authentication/auth servers/auth server/system%20local/local/users/user h 'content type application/json' d '{"change password at signin" "false", "console access" "false", "enabled" "true", "fullname" "user0001", "one time use" "false", "password cleartext" "'xxxxxxx", "username" "user0002"}' response http/1 1 201 created content type application/json content length 128 { "result" { "warnings" \[ { "message" "the configuration has been implicitly changed" } ] } } put api call update full name field of specific user request put /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user/user0001/fullname http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json cache control no cache { "fullname" "rest api test for user0001" } response http/1 1 200 ok content length 122 content type application/json { "result" { "info" \[ { "message" "operation succeed without warning or error!" } ] } } equivalent curl command command curl i u hv5uaqowf5kuisvnuigeabol8fsczsk98zvwphywgke= x put https //\<hostname>/api/v1/configuration/authentication/auth servers/auth server/system%20local/local/users/user/user0001/fullname h 'content type application/json' d '{"fullname" "user0001"}' response http/1 1 200 ok content type application/json content length 124 { "result" { "info" \[ { "message" "operation succeeded without warning or error!" } ] } } after updating, fetch the user details and observe the fullname field updated request get /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user/user0001 http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json response http/1 1 200 ok content length →327 content type →application/json { "change password at signin" "false", "console access" "false", "enabled" "true", "fullname" "rest api test for user0001", "one time use" "false", "password cleartext" "'xxxxxxx", "username" "user0001" } delete api call delete specific user request delete /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user/user0001 http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json response http/1 1 200 ok content length →122 content type →application/json { "result" { "info" \[ { "message" "operation succeed without warning or error!" } ] } } equivalent curl command command curl i u hv5uaqowf5kuisvnuigeabol8fsczsk98zvwphywgke= x delete https //\<hostname>/api/v1/configuration/authentication/auth servers/auth server/system%20local/local/users/user/user0002/ response http/1 1 204 no content content type application/json content length 0 after deleting, try to fetch the resource and you would observe 404 response request get /api/v1/configuration/authentication/auth servers/auth server/sys local/local/users/user/user0001 http/1 1 host xx xxx xxx xxx authorization basic cdkvadg1exrfbwteenzrr1ntutr6nzdwnllhn2fmsum0mnzomey5q0dhut06 content type application/json cache control no cache response 404 not found content length 105 content type application/json { "result" { "errors" \[ { "message" "resource does not exist " } ] } } representing configuration resources using links when performing a get request on a configuration resource, the json response may have "href" attributes to represent smaller resources within as an example, "get /api/v1/configuration" returns { "users" { "href" "/api/v1/configuration/users" }, "system" { "href" "/api/v1/configuration/system" }, "authentication" { "href" "/api/v1/configuration/authentication" }, "administrators" { "href" "/api/v1/configuration/administrators" } } the href values can be used to access smaller resources sample get/post/put/delete request and responses in ips below is a sample of get/post/put/delete request and responses get api call fetch the details under endpoint policy this example shows how to fetch the details under endpoint policy in ips request get /api/v1/configuration/uac http/1 1 host xx xx xx xx authorization basic vu9qstlgtznryvk5d0t2axpbn1dpz0fyzln1s3fmtknnquh0r0zur0xsbz06 content type application/json { "admissioncontrol" { "href" "/api/v1/configuration/uac/admissioncontrol" }, "host enforcer" { "href" "/api/v1/configuration/uac/host enforcer" }, "infranet enforcer" { "href" "/api/v1/configuration/uac/infranet enforcer" }, "mac address realms" { "href" "/api/v1/configuration/uac/mac address realms" }, "network access" { "href" "/api/v1/configuration/uac/network access" }, "snmpenforcement" { "href" "/api/v1/configuration/uac/snmpenforcement" } } response http/1 1 200 ok content length 340 content type application/json equivalent curl command command curl i u g4dnct4699c+iwip/+8urgxm0luy1vqdj9znxefwebm= x get https //\<hostname>/api/v1/configuration/uac response http/1 1 200 ok content type application/json content length 620 { "admissioncontrol" { "href" "/api/v1/configuration/uac/admissioncontrol" }, "host enforcer" { "href" "/api/v1/configuration/uac/host enforcer" }, "infranet enforcer" { "href" "/api/v1/configuration/uac/infranet enforcer" }, "mac address realms" { "href" "/api/v1/configuration/uac/mac address realms" }, "network access" { "href" "/api/v1/configuration/uac/network access" }, "networkdeviceadministration" { "href" "/api/v1/configuration/uac/networkdeviceadministration" }, "snmpenforcement" { "href" "/api/v1/configuration/uac/snmpenforcement" } post api call create an srx enforcer in infranet enforcer connection this example shows how to create an srx enforcer in infranet enforcer connection request post /api/v1/configuration/uac/infranet enforcer/connections/infranet enforcer/ http/1 1 host xx xx xx xx authorization basic vu9qstlgtznryvk5d0t2axpbn1dpz0fyzln1s3fmtknnquh0r0zur0xsbz06 content type application/json { "idp for local sessions only" "true", "junos" { "location group" " no 802 1x ", "password encrypted" "3u+ur6n8agabaaaaofsnibru19vdwuslg5lg4cg1qh6cbxdsmy4zw0x85hy=" }, "name" "srx", "serial number" \[ "sjfioqji4knm" ], "severity filter" "medium", "use idp" "false" } response http/1 1 201 ok content length 122 content type application/json { "result" { "info" \[ { "message" "operation succeed without warning or error!" } ] } } equivalent curl command command curl i u g4dnct4699c+iwip/+8urgxm0luy1vqdj9znxefwebm= x post https //\<hostname>/api/v1/configuration/uac/infranet enforcer/connections/infranet enforcer h 'content type application/json' d '{"idp for local sessions only" "true", "junos" { "location group" " no 802 1x ", "password encrypted" "3u+ur6n8agabaaaaofsnibru19vdwuslg5lg4cg1qh6cbxdsmy4zw0x85hy=" },"name" "srx","serial number" \["sjfioqji4knm"],"severity filter" "medium", "use idp" "false"}' response http/1 1 201 created content type application/json content length 124 { "result" { "info" \[ { "message" "operation succeeded without warning or error!" } ] } } put api call update existing configuration where in initial location group is configured as guest this example updates the existing configuration where in the initial location group is configured as "guest" and then later updated to "default" location group before updating the location group request get api/v1/configuration/uac/network access/radius clients/radius client/radius%20client http/1 1 host xx xx xx xx authorization basic vu9qstlgtznryvk5d0t2axpbn1dpz0fyzln1s3fmtknnquh0r0zur0xsbz06 content type application/json { "location group" "guest", "name" "radius client", } response http/1 1 200 ok content length 122 content type application/json equivalent curl command command curl i u g4dnct4699c+iwip/+8urgxm0luy1vqdj9znxefwebm= x put https //\<hostname>/api/v1/configuration/uac/network access/radius clients/radius client/radius%20client h 'content type application/json' d '{"location group" "default","name" "radius client"}’ response http/1 1 200 ok content type application/json content length 124 { "result" { "info" \[ { "message" "operation succeeded without warning or error!" } ] } } after updating the location group request put api/v1/configuration/uac/network access/radius clients/radius client/radius%20client http/1 1 host xx xx xx xx authorization basic vu9qstlgtznryvk5d0t2axpbn1dpz0fyzln1s3fmtknnquh0r0zur0xsbz06 content type application/json { "location group" "default", "name" "radius client", } response http/1 1 200 ok content length 122 content type application/json { "result" { "info" \[ { "message" "operation succeed without warning or error!" } ] } } delete api call delete an snmp device this example shows how to delete snmp device from ips request delete api/v1/configuration/uac/snmpenforcement/clients/client/ruckus http/1 1 host xx xxx xxx xxx authorization basic vu9qstlgtznryvk5d0t2axpbn1dpz0fyzln1s3fmtknnquh0r0zur0xsbz06 content type application/json response http/1 1 204 no content content length 0 content type application/json equivalent curl command command curl i u g4dnct4699c+iwip/+8urgxm0luy1vqdj9znxefwebm= x delete https //\<hostname>/api/v1/configuration/uac/snmpenforcement/clients/client/ruckus response http/1 1 204 no content content type application/json content length 0