- OTIS Documentation
- OTIS Restful Protocol Overview
- OTIS Error Responses
- ActiveRoles/[$roleID] GET
- ActiveRoles PUT
- AssumableRoles GET
- Entity/$entityID/Attribute/$attrID PUT
- Entity/$entityID/Attribute/$attrID GET
- Entity/$entityID/Attribute POST
- AuditLog PUT
- entityID GET
- AuthenticatedSession/$sessionID GET
- AuthenticatedSession POST
- AuthenticatedSession/$sessionID PUT
- Context[?attr=$attrID[&attr=$attrIDn]...] GET
- Context/ PUT Message
- Entity/$entityID[?attr=$attrID[&attr=$attrIDn]...] GET
- Entity/ POST
- Entity/$entityID PUT
- Properties[/$propertyName] GET
- Properties/$propertyName PUT
Context/ PUT Message
This page documents the format and semantics of the request and response messages for a PUT operation which modifies a context.
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 update an entity in the context of an authenticated session:
http://$HostName/$OtisAppName/AuthenticatedSession/$sessionID/Context
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).
Request Message Format
The content of the response message is a ContextChanges 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
!
-->
<!--
Example of making a few modifications to a context
-->
<!--
This would be sent to a PUT on an address like <service>/Context
-->
<tns:ContextChange xmlns:tns="http://www.eclipse.org/higgins/idas/rest-xml/2008/6"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.eclipse.org/higgins/idas/rest-xml/2008/6 ../rest-xml.xsd "
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!--
Replace the administrative entity (attribute) for this context.
We do this by removing the old attribute and re-adding it.
-->
<tns:AttributeRemove>http://example.com/ontologies/person/2008/6#adminEntity</tns:AttributeRemove>
<tns:Attribute attrID="http://example.com/ontologies/person/2008/6#adminEntity">
<tns:AttributeValue valType="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#RelativeEntityUDI">
<tns:SimpleData xsi:type="xsd:string">Jimse</tns:SimpleData>
</tns:AttributeValue>
</tns:Attribute>
<!--
Do the same thing as above, but by manipulating values rather
than the entire attribute. This assumes we know the old value.
-->
<tns:AttributeChange attrID="http://example.com/ontologies/person/2008/6#adminEntity">
<tns:AttributeValueRemove valType="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#RelativeEntityUDI">
<tns:SimpleData>George</tns:SimpleData>
</tns:AttributeValueRemove>
<tns:AttributeValue valType="http://www.eclipse.org/higgins/ontologies/2008/6/higgins#RelativeEntityUDI">
<tns:SimpleData>Jimse</tns:SimpleData>
</tns:AttributeValue>
</tns:AttributeChange>
<!-- Remove an entity -->
<tns:EntityRemove>George</tns:EntityRemove>
<!-- Add an entity -->
<tns:Entity entityType="http://example.com/ontologies/person/2008/6#person">
<!--
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">George</tns:SimpleData>
</tns:AttributeValue>
</tns:Attribute>
</tns:Entity>
<!-- Update an existing entity -->
<tns:EntityChange entityID="jimse">
<!--
Add a new attribute/value. If this attribute already exists, the new
value(s) will be added. If not, the Attribute is created with the
specified attribute(s)
-->
<tns:Attribute attrID="http://example.com/ontologies/person/2008/6#surname">
<tns:AttributeValue valType="http://www.w3.org/2001/XMLSchema#string">
<tns:SimpleData xsi:type="xsd:string">sermersheim</tns:SimpleData>
</tns:AttributeValue>
</tns:Attribute>
</tns:EntityChange>
</tns:ContextChange>Request Elements and Attributes
- ContextChange element This is always the root element for the request message.
- Entity element When present, causes the specified new entity to be added.
- EntityRemove element When present, causes the specified entity to be removed.
- EntityChange element When present, causes the specified entity to be updated.
- Attribute element When present, causes the specified attribute to be added.
- AttributeRemove element When present, causes the specified attribute to be removed.
- AttributeChange element When present, specifies updates to attributes for the entity.
- AttributeChange element When present, is used to update the attributes of this attribute (these may be meta-attributes, and/or sub-attributes of a complex attribute).
- AttributeValue element When present, causes the specified attribute value to be added.
- AttributeValueRemove element When present, causes the specified attribute value to be removed.
- AttributeValueChange element When present, is used to update values on the attribute specified in the AttributeValueChange.
- ChangeValue element When present, identifies the value being changed. Must be present when the attribute is multi-valued.
- Attribute element When present, causes the specified attribute to be added.
- AttributeRemove element When present, causes the specified attribute to be removed.
- AttributeChange element When present, specifies updates to attributes for the entity.
- attrID attribute When present, causes the specified attribute to be updated. There will always be one or more AttributeChange and/or one or more AttributeValueChange elements present when this is present.
- entityID attribute When present, causes the specified entity to be updated. There will always be one or more AttributeChange elements present when this is present.
- Attribute element When present, causes the specified attribute to be added to the context.
- AttributeRemove element When present, causes the specified attribute to be removed from the context.
- AttributeChange element Used to specify updates to attributes for the context.
Response Message Format
If the request to modify a context 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 response message will empty, and the HTTP response code will be 200 (success).
