resource rendering options - lithnet/resourcemanagement-webservice GitHub Wiki

The v2 API provides several different options for controlling how resources are represented via the API. These optional parameters can be used in conjunction with the following API calls

Requests

Augment the existing request and parameters with the additional parameters required

Method URL
GET /v2/resources/{id}/?{valueFormat}&{includeNullAttributes}&{resourceFormat}&{arrayHandling}
GET /v2/resources/?filter={filter}?{valueFormat}&{includeNullAttributes}&{resourceFormat}&{arrayHandling}
GET /v2/resources/?objectType={objectType}&attributes={attributes}&{valueFormat}&{includeNullAttributes}&{resourceFormat}&{arrayHandling}

URL Parameters

Parameter name Allowed Values Description
{valueFormat} default string Setting valueFormat=string will return all values as JSON strings. By default, numbers and Boolean values appear as their native JSON data types
{includeNullAttributes} true false Setting includeNullAttributes=true will return attributes that do not have a value. By default, attributes with null values are not returned in the response
{resourceFormat} default fixed Setting resourceFormat=fixed will present the resource in a format that is consumable without knowing the schema in advance. Rather than displaying attribute/value pairs, the resource is rendered as attribute objects, that have separate name and value properties.
{arrayHandling} default all Setting arrayHandling=all forces all attribute values to be presented as arrays. By default, only attributes defined as multivalued in the FIM schema are presented as arrays.

Examples

valueFormat

valueFormat=default

The following shows a request with valueFormat=default. Numbers and Boolean values appear as their native JSON data type. The valueFormat parameter can be omitted when using the default setting as shown in the request examples below.

Request

GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/?valueFormat=default
GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/

Response

HTTP/1.1 200 OK

{
    "ObjectType": "Person",
    "ObjectID": "64f62191-b255-443b-bbe4-491a66300725",
    "ObjectSID": "AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA==",
    "CreatedTime": "2015-06-02T09:13:57.037",
    "Creator": "fb89aefa-5ea1-47f1-8890-abe7797d6497",
    "DomainConfiguration": "1aff46f4-5511-452d-bcbd-7f7b34b0fe14",
    "Manager": "64f62191-b255-443b-bbe4-491a66300725",
    "AccountName": "testuser",
    "AccountDisabled": true,
    "UnixUid": 554422,
    "DisplayName": "Test User",
    "Domain": "FIM-DEV1",
    "Email": "[email protected]",
    "FirstName": "Test",
    "JobTitle": "Test User",
    "LastName": "User",
    "MVObjectID": "{7612EEDA-551E-E511-8CDB-005056B50BB9}",
    "jobTitles": [
        "Test1",
        "Test2"
    ],
}

valueFormat=string

The following shows a request with valueFormat=string. Numbers and boolean values appear as strings

Request

GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/?valueFormat=string

Response

HTTP/1.1 200 OK

{
    "ObjectType": "Person",
    "ObjectID": "64f62191-b255-443b-bbe4-491a66300725",
    "ObjectSID": "AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA==",
    "CreatedTime": "2015-06-02T09:13:57.037",
    "Creator": "fb89aefa-5ea1-47f1-8890-abe7797d6497",
    "DomainConfiguration": "1aff46f4-5511-452d-bcbd-7f7b34b0fe14",
    "Manager": "64f62191-b255-443b-bbe4-491a66300725",
    "AccountName": "testuser",
    "AccountDisabled": "True",
    "UnixUid": "554422",
    "DisplayName": "Test User",
    "Domain": "FIM-DEV1",
    "Email": "[email protected]",
    "FirstName": "Test",
    "JobTitle": "Test User",
    "LastName": "User",
    "MVObjectID": "{7612EEDA-551E-E511-8CDB-005056B50BB9}",
    "jobTitles": [
        "Test1",
        "Test2"
    ],
}

includeNullAttributes

includeNullAttributes=true

By default, the API will not return attributes that have a null value in the response body. Using this parameter allows you to request that all attributes are returned in the response. Single-valued attributes are shown as null, whereas multivalued attributes are presented as an empty array []

Request

GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/?includeNullAttributes=true

Response

HTTP/1.1 200 OK

{
    "ObjectType": "Person",
    "ObjectID": "64f62191-b255-443b-bbe4-491a66300725",
    "ObjectSID": "AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA==",
    "CreatedTime": "2015-06-02T09:13:57.037",
    "Creator": "fb89aefa-5ea1-47f1-8890-abe7797d6497",
    "DomainConfiguration": "1aff46f4-5511-452d-bcbd-7f7b34b0fe14",
    "Manager": "64f62191-b255-443b-bbe4-491a66300725",
    "AccountName": "testuser",
    "AccountDisabled": true,
    "UnixUid": 554422,
    "DisplayName": "Test User",
    "Domain": "FIM-DEV1",
    "Email": "[email protected]",
    "FirstName": "Test",
    "JobTitle": "Test User",
    "LastName": "User",
    "MVObjectID": "{7612EEDA-551E-E511-8CDB-005056B50BB9}",
    "jobTitles": [
        "Test1",
        "Test2"
    ],
    "AuthNWFRegistered": [ ],
    "Location": null,
    "Country": null,
    "Office": null,
    "TelephoneNumbers": [ ]
}

resourceFormat

resourceFormat=fixed

By default, the API returns values in attribute/value pairs. However, this requires the consuming application to know the resource schema in advance. The fixed resource format presents the resource using a fixed representation, that is not dependent on the resource schema

Request

GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/?resourceFormat=fixed

Response

HTTP/1.1 200 OK

{
	"Resource": [{
		"Name": "ObjectType",
		"Values": [
			"Person"
		]
	}, {
		"Name": "ObjectID",
		"Values": [
			"64f62191-b255-443b-bbe4-491a66300725"
		]
	}, {
		"Name": "ObjectSID",
		"Values": [
			"AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA=="
		]
	}, {
		"Name": "AccountDisabled",
		"Values": [
			true
		]
	}, {
		"Name": "CreatedTime",
		"Values": [
			"2016-05-03T13:44:07.947"
		]
	}, {
		"Name": "UnixUid",
		"Values": [
			1403323
		]
	}, {
		"Name": "Creator",
		"Values": [
			"fb89aefa-5ea1-47f1-8890-abe7797d6497"
		]
	}, {
		"Name": "DomainConfiguration",
		"Values": [
			"1aff46f4-5511-452d-bcbd-7f7b34b0fe14"
		]
	}, {
		"Name": "AccountName",
		"Values": [
			"testuser"
		]
	}, {
		"Name": "DisplayName",
		"Values": [
			"Test User"
		]
	}, {
		"Name": "Domain",
		"Values": [
			"FIM-DEV1"
		]
	}, {
		"Name": "Email",
		"Values": [
			"[email protected]"
		]
	}, {
		"Name": "FirstName",
		"Values": [
			"Test"
		]
	}, {
		"Name": "jobTitles",
		"Values": [
			"Test1",
			"Test2"
		]
	}, {
		"Name": "LastName",
		"Values": [
			"User"
		]
	}, {
		"Name": "MVObjectID",
		"Values": [
			"{7612EEDA-551E-E511-8CDB-005056B50BB9}"
		]
	}]
}

arrayHandling

arrayHandling=all

By default, the API will return multi-valued attributes as JSON arrays and single-valued attributes as a non-arrayed single element. The API can return all values as JSON arrays, by setting the arrayHandling parameter to all.

Request

GET /v2/resources/64f62191-b255-443b-bbe4-491a66300725/?arrayHandling=all

Response

HTTP/1.1 200 OK

{
  "ObjectType": [
    "Person"
  ],
  "ObjectID": [
    "64f62191-b255-443b-bbe4-491a66300725"
  ],
  "ObjectSID": [
    "AQUAAAAAAAUVAAAAFYLkaG78nJrWb05iFacCAA=="
  ],
  "CreatedTime": [
    "2015-06-02T09:13:57.037"
  ],
  "Creator": [
    "fb89aefa-5ea1-47f1-8890-abe7797d6497"
  ],
  "DomainConfiguration": [
    "1aff46f4-5511-452d-bcbd-7f7b34b0fe14"
  ],
  "Manager": [
    "64f62191-b255-443b-bbe4-491a66300725"
  ],
  "AccountName": [
    "testuser"
  ],
  "AccountDisabled": [
    true
  ],
  "UnixUid": [
    554422
  ],
  "DisplayName": [
    "Test User"
  ],
  "Domain": [
    "FIM-DEV1"
  ],
  "Email": [
    "[email protected]"
  ],
  "FirstName": [
    "Test"
  ],
  "JobTitle": [
    "Test User"
  ],
  "LastName": [
    "User"
  ],
  "MVObjectID": [
    "{7612EEDA-551E-E511-8CDB-005056B50BB9}"
  ],
  "jobTitles": [
    "Test1",
    "Test2"
  ]
}
⚠️ **GitHub.com Fallback** ⚠️