Context[?attr=$attrID[&attr=$attrIDn]...] GET

This page documents the format and semantics of the request message to read the entities of a context and the response message that the Otis Service sends in response.

Notational Conventions

• Variables are represented using a $variable notation. For example, the $HostName variable represents a server host name. An actual value for $HostName might be something like "code.bandit-project.org".
• Characters are appended to elements and attributes to indicate cardinality:
  • "?" (0 or 1)
  • "*" (0 or more)
  • "+" (1 or more)
• The character "|" is used to indicate a choice between alternatives.
• Items contained in braces ("{" and "}") are used to indicate that contained items are to be treated as a group.

Request Noun URL

The following URL is the "noun" that is used to query the entities in the context of an authenticated session:

http://$HostName/$OtisAppName/AuthenticatedSession/$sessionID/Context[?attr=$attrID[&attr=$attrIDn]...]

For example, the following URL would get a set of default attributes (determined by OTIS configuration) for all entities in the currently open context.

http://code.bandit-project.org/otis/AuthenticatedSession/78BD660E0E5F673378BD660E0E5F6733/Context

the following URl would get the attributes phoneNumber and email attributes for the entities:

http://code.bandit-project.org/otis/AuthenticatedSession/78BD660E0E5F673378BD660E0E5F6733/Context?attr=phoneNumber&attr=email

NOTE: Actual attribute IDs are likely to be full URLs, 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

 ?attr=http%3A%2F%2Fschemas.xmlsoap.org%2Fws%2F2005%2F05%2Fidentity%2Fclaims%2Fgivenname

Session Secret

When a session is first created, the OTIS server may assign a secret to the session. Whether or not a session secret is created depends on a setting in the OTIS server called SessionSecretBitSize. See here for documentation on this setting. If a size of zero is specified, no session secret will be created. If a session secret is created, it will be returned to the client in the first response message the OTIS server sends back to the client during authentication. For more detail on this response, see here. Thereafter, the client is expected to send the secret in an HTTP header called SessionSecret whenever it wants to perform actions on the session. If the session secret is not provided, or does not match the one OTIS has for the session, the request will be rejected. NOTE: The header is NOT required if no session secret has been generated by OTIS (SessionSecretBitSize == 0).

Response Message Format

If the request to read an entity fails, the HTTP response code will contain an error code, and the content of the response will contain additional information. For more information on error responses, see here. Otherwise, the content of the response message is an Context element as defined in the [higgins rest.xsd]. An example is shown here:

<?xml version="1.0" encoding="UTF-8"?>
<!--
 ! Copyright (c) 2008 Novell, Inc.
 ! All rights reserved. This program and the accompanying materials
 ! are made available under the terms of the Eclipse Public License v1.0
 ! which accompanies this distribution, and is available at
 ! http://www.eclipse.org/legal/epl-v10.html
 !
 ! Contributors:
 !              Jim Sermersheim
 !              Daniel Sanders
 !
-->
        <!--
                This might come back from a GET of an address like
                <service>/Context
        -->
<tns:Context xmlns:tns="http://www.eclipse.org/higgins/idas/rest-xml/2008/6"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:higgins="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#"
        xsi:schemaLocation="http://www.eclipse.org/higgins/idas/rest-xml/2008/6 ../rest-xml.xsd ">
        <tns:Entity entityType="http://example.com/ontologies/person/2008/6#person" entityID="jimse">
                <!--
                        The required entityId attribute. Note that here we illustrate meta
                        data on the value
                -->
                <tns:Attribute
                        attrID="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#entityId">
                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                <tns:SimpleData xsi:type="xsd:string">jimse</tns:SimpleData>
                                <tns:Attribute
                                        attrID="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#lastModified">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#dateTime">
                                                <tns:SimpleData xsi:type="xsd:dateTime">2008-06-26T10:55:12Z</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                        </tns:AttributeValue>
                </tns:Attribute>
                <!-- An example of a multi-valued attribute with two literal values -->
                <tns:Attribute
                        attrID="http://example.com/ontologies/person/2008/6#emailAddress">
                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                <tns:SimpleData xsi:type="xsd:string">jimse@novell.com</tns:SimpleData>
                        </tns:AttributeValue>
                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                <tns:SimpleData xsi:type="xsd:string">jimse@gmail.com</tns:SimpleData>
                        </tns:AttributeValue>
                </tns:Attribute>
                <!-- A single-valued complex attribute -->
                <tns:Attribute
                        attrID="http://example.com/ontologies/person/2008/6#homeAddress">
                        <tns:AttributeValue valType="http://example.com/ontologies/person/2008/6#postalAddress">
                                <tns:Attribute
                                attrID="http://example.com/ontologies/person/2008/6#houseNumber">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                                <tns:SimpleData xsi:type="xsd:string">123</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                                <tns:Attribute attrID="http://example.com/ontologies/person/2008/6#street">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                                <tns:SimpleData xsi:type="xsd:string">East Morningwood Drive</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                                <tns:Attribute attrID="http://example.com/ontologies/person/2008/6#city">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                                <tns:SimpleData xsi:type="xsd:string">Anytown</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                                <tns:Attribute attrID="http://example.com/ontologies/person/2008/6#state">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                                <tns:SimpleData xsi:type="xsd:string">Calgafornia</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                                <tns:Attribute attrID="http://example.com/ontologies/person/2008/6#zip">
                                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#integer">
                                                <tns:SimpleData >10293</tns:SimpleData>
                                        </tns:AttributeValue>
                                </tns:Attribute>
                        </tns:AttributeValue>
                </tns:Attribute>
                <!-- An attribute with two values, each a different type -->
                <tns:Attribute attrID="http://example.com/ontologies/person/2008/6#friend">
                        <tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
                                <tns:SimpleData xsi:type="xsd:string">john.doe@example.com</tns:SimpleData>
                        </tns:AttributeValue>
                        <tns:AttributeValue valType="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#RelativeEntityUDI">
                                <tns:SimpleData xsi:type="xsd:string">George</tns:SimpleData>
                        </tns:AttributeValue>
                </tns:Attribute>
        </tns:Entity>
</tns:Context>

Response Elements and Attributes

• Context element This is always the root element for the response message.
• Entity element There will be an Entity element for each returned entity.
  • entityType attribute Specifies the entity type
  • entityID attribute Specifies the entity ID. NOTE: This attribute, if present, will have the same value that is contained in the attribute whose AttrID is http://www.eclipse.org/higgins/ontologies/2008/6/higgins#entityId.
  • Attribute element. These hold the attributes of the entity. At least one exists which has the attrID of http://www.eclipse.org/higgins/ontologies/2008/6/higgins#entityId
    • AttributeValue element Holds value of the attribute as well as any metadata pertaining to that attribute value
      • valType attribute URI that specifies the datatype of the attribute value.
      • SimpleData element Holds the actual data of the attribute value when the value type is a literal (simple type).
      • Attribute element When the value type is simple, these all represent metadata about that attribute value. When the value type is complex, these can comprise parts of the complex attributes as well as metadata about the attribute value in general. It is up to the caller to understand the difference between elements which represent meta-data versus attribute value components. This is typically done via some a-priori knowledge or by interrogating the model of the attribute value type.