Chat now with support
Chat with Support

Identity Manager 8.1 - REST API Reference Guide

Query parameters

Query parameters are included in the URI path using a question mark or ampersand. For example, to receive a list of people ordered by their surname, after specifying the table person as a path parameter, you specify an orderBy as a query parameter. The following shows the URI format for this request, and an example:

<BaseURL>/api/entities/{table}

Example:

https://<Hostname>/AppServer/api/entities/person?orderBy=LastName

The first query parameter is preceded by a question mark, using the following format:

?parameterName=parameterValue

Subsequent query parameters are preceded by an ampersand, using the following format:

&parameterName=parameterValue

For example, to get all people who are marked as external ordered by their company membership, use the following request:

https://<Hostname>/AppServer/api/entities/person?where=IsExternal%3D0&orderBy=CompanyMember

NOTE: If a parameter is not shown in a request’s URI format with a slash, it is a query parameter; the URI format for a request shows only the path parameters. The description that follows each URI format provides information on the query parameters, if any.

HTTP request methods

Depending on the HTTP request, use one of the following HTTP request methods:

  • Get: Use for requests that retrieve elements from the application server.
  • Put: Use for requests that change elements on the application server.
  • Post: Use for requests that create an element on the application server.
  • Delete: Use for request that delete an element on the application server.

The request methods Put and Post will also be used if:

  • The number or the size of the parameters would lead to problems in the URL.
  • The type of parameter would lead to problems in the URL.

Each request description specifies which HTTP request method to use.

To use these request methods on an application server they must be permitted by the web server.

Response formats

Code-issued requests to the API should always return JSON, based on the request headers.

To return JSON output

  • Set the Accept header in the request to application/json.

HTTP response codes

Responses from the REST API use the codes listed below. When method executions fail, a descriptive error message is displayed.

Table 1: HTTP response codes

Response status codes

Description

200

Success

204

Success. No content returned.

401

Unauthorized. To use the One Identity Manager REST API, you first have to authenticate it against the application server.

404

Not found. The requested entity is not found.

405

Method not allowed. The HTTP request method that was specified is not the correct method for the request.

500

Internal server error. The error message is returned in the property error string of the response.

{
	"responseStatus": {
		"message": "Sample text"},
	"errorString": "Sample text",
	"exceptions": [{
		"number": 810017,
		"message": "Sample text"}
	]
}

Due to security, the detailed error message will not be returned to the caller. More information can be retrieved from the application server log on the application server.

Related Documents