1. OTIS Documentation
    1. Overview
    2. Deploying an OTIS Server
    3. Developer Documentation
      1. OTIS Functionality
      2. Samples
      3. OTIS RESTful Protocol Details
      4. Audit Logging
    4. Configuration Documentation
  2. Entity and Attribute Tasks
  3. Create Attribute
    1. REST
    2. Java
    3. PHP
    4. cURL
  4. Create Entity
    1. REST
    2. Java
    3. PHP
    4. cURL
  5. Delete Attribute
    1. REST
    2. Java
    3. PHP
    4. cURL
  6. Delete Entity
    1. REST
    2. Java
    3. PHP
    4. cURL
  7. Read Attribute
    1. REST
    2. Java
    3. PHP
    4. cURL
  8. Read Context
    1. REST
    2. Java
    3. PHP
    4. cURL
  9. Read Entity
    1. REST
    2. Java
    3. PHP
    4. cURL
  10. Update Attribute
    1. REST
    2. Java
    3. PHP
    4. cURL
  11. Update Entity
    1. REST
    2. Java
    3. PHP
    4. cURL

Read Attribute

This section provides developers with information on how to read a specified attribute from a specified entity. Documentation for the REST protocol, as well as code samples for Java, PHP, and cURL, are provided below.

REST

The REST noun (and associated message content) for reading an attribute from a specified entity is as follows:

  • Relative Noun: AuthenticatedSession/$sessionID/Entity/$entityID/Attribute/$attrID. This is the relative path of the URL that should appear after the OTIS server application name. Below is an example of reading the phoneNumber attribute on the john.doe entity: 
    AuthenticatedSession/78BD660E0E5F673378BD660E0E5F6733/Entity/john.doe/Attribute/phoneNumber
    NOTE: Actual attribute IDs are likely to be full URIs, and would need to be URL encoded. For example, the attribute: 
    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
    would be encoded as 
    http%3A%252F%252Fschemas.xmlsoap.org%252Fws%252F2005%252F05%252Fidentity%252Fclaims%252Fgivenname

IMPORTANT NOTE ON ENCODING: Characters which have special meanings in URLs (such as '/', '?', and '&') might need to be double encoded in order to ensure that they arrive at OTIS still encoded. This is because web servers often decode the URL before handing it to a web service application (like OTIS). In the example above you see some %252F encodings. If a web server decodes this before handing it to OTIS, it appears in the URL as %2F (because %25 decodes to %). If you simply put %2F in the URL, the web server decodes it to '/', which causes OTIS to improperly parse the URL's path component. Similar arguments can be made about encodings for the '?' and '&' characters.

  • HTTP Method: GET.
  • Request/Response message details: <Attribute> element details.
  • Description: Reads the specified attribute from the specified entity.

Java

The following is example Java code that demonstrates how to read the specified attribute from the specified entity: 

Iterator attributes = example.getAttributes();
while(attributes.hasNext()) {
     IAttribute exampleAttribute = (IAttribute)attributes.next();
     System.out.println("\t" + ((ISimpleAttrValue)exampleAttribute
     .getValues().next()).getCanonical());       //only returns the first value in the Iterator
}

To view the complete Java sample code for Attribute/Entity nouns, see the Entity/Attribute Java Sample Code page.

The OTIS client Java library may be downloaded from the OTIS download page.

PHP

THe following is example PHP code that demonstrates how to read the specified attribute from the specified entity: 

//Make a get request for the attribute with the following URLs
$attribute = getRequest($sessionURL, $sessionSecret, "Entity/otisTest/Attribute/givenname");
echo $attribute;

//OR (if attribute is something other than givenname or surname)
$attribute = getRequest($URL, $sessionSecret, "Entity/example/Attribute/http%3A%252F%252Fschemas.xmlsoap.org%252Fws%252F2005%252F05%252Fidentity%252Fclaims%252Femailaddress");


function getRequest($URL, $secret, $URI){
	//Generate the header to get the entity
	$getHeader = 
	"GET $URL/$URI HTTP/1.1\n".
	"Host: wag.bandit-project.org\n".
	(($secret) ? ("SessionSecret: " . $secret . "\n") : "") .
	"Connection: Close\n\n";
	$socket = fsockopen("wag.bandit-project.org", 80);
	fputs($socket, $getHeader);
	$xml = "";
	while (!feof($socket)) 
	{
		$content = fgets($socket, 256);
		//If the line contains an xml tag, add it to the xml var
		if(strpos($content, ">")){
			$xml .= $content;
		}
	}
	//Return the xml var
	return($xml);
}

To view the complete PHP sample code for Attribute/Entity nouns, see the Entity/Attribute PHP Sample Code page.

cURL

The following command reads the "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" attribute on the "otistest" entity 

if [ -e secret.hdr ] ; then secret=`cat secret.hdr` ; else secret="nosecret: none" ; fi
curl -b cookies.txt -H "${secret}" https://wag.bandit-project.org/otis/Entity/otistest/Attribute/http%3A%252F%252Fschemas.xmlsoap.org%252Fws%252F2005%252F05%252Fidentity%252Fclaims%252Fsurname
This assumes you have already set up an authenticated session and are using a cookies.txt file to store/retrieve the otisSessionID cookie. It also assumes that the session secret has been stored in a file called secret.hdr (see Authenticate User for details).

See the Attribute Get Request documentation for further details including expected response codes and message body.