OTIS Restful Protocol Overview
Architecturally, OTIS follows the principals of [REST], and is intended to be accessible a wide variety of client libraries.
The representation or data model proposed by OTIS is similar to Google's [GData], being based on [Atom 1.0] and the [Atom Publishing Protocol].
Resources or nouns in the system are all identified via [URIs].
Notational Conventions
- We have only documented the part of the URL that would appear after the scheme, host name, and web application name. If the OTIS server host name were code.bandit-project.org, and the OTIS application were otis, the nouns described below would be prepended with https://code.bandit-project.org/otis/.
- Variable parts of the noun are represented as $variable. In instances of the URL, the $variable part is replaced with an actual value. For example, the $sessionID variable represents a session identifier on the OTIS server. An actual value for $sessionID might be something like "7A8B3C4D5E6F11298F546ABBCDC35FAA".
- Optional parts of a noun are enclosed in brackets [].
Authenticated 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. Essentially, this HTTP header will need to be sent for every noun below that begins with AuthenticatedSession/$sessionID - as those are the nouns that operate on authenticated sessions. NOTE: The header is NOT required if no session secret has been generated by OTIS (SessionSecretBitSize == 0).
Specifying a Version for Resources
To ensure compatibility between OTIS clients and servers, a client should be able to specify the format of the message body it expects when accessing a resource. The client does this by specifying one or more media types in the HTTP Accept header (see Section 14.1 of [RFC2616]). The message bodies described in this documentation conform to the content type application/x-vnd.org.bandit.otis-v1+xml. As such, clients should place an Accept: application/x-vnd.org.bandit.otis-v1+xml in their HTTP headers.
By default. when a client does not specify an Accept header, or when it is set to */* or application/*, the resulting response message body content type will be set to application/x-vnd.org.bandit.otis-v1+xml. Also by default, if a client passes an Accept of text/* or text/xml (or various others) the message body will still be encoded as specified in this document, but the HTTP Content-Type will be set to a value appropriate to the client's Accept header (i.e. text/xml).
If the client wishes to be forward-compatible with future versions of OTIS, it is strongly recommended that it send the Accept: application/x-vnd.org.bandit.otis-v1+xml media type header.
Note that the OTIS server may be configured to map Accept media types sent by the client to any number of resulting Content-Type message formats. Default mappings and configuration settings are noted here
Authentication Nouns
| Resource / Noun | Method | Request/Response Content | Description |
| AuthenticatedSession | POST | details | Create an authenticated session. |
| AuthenticatedSession/$sessionID | PUT | details | Update the authenticated session specified by the $sessionID variable. May be used to reauthenticate a session that has been previously authenticated or provide additional authentication materials for a session that is currently in the process of being authenticated. |
| AuthenticatedSession/$sessionID | GET | details | Query the authenticated session specified by the $sessionID variable. |
| AuthenticatedSession/$sessionID | DELETE | None | Delete the authenticated session specified by the $sessionID variable. |
Role Nouns
| Resource / Noun | Method | Request/Response Content | Description |
| AuthenticatedSession/$sessionID/ActiveRoles[/$roleID] | GET | details | Query the currently active roles in the authenticated session specified by the $sessionID variable. If the $roleID variable is specified, this is an "is in role" query to determine if the specified role is currently active for the session. |
| AuthenticatedSession/$sessionID/ActiveRoles | PUT | details | Update the list of active roles for the authenticated session specified by the $sessionID variable. The PUT operation allows a role to be activated for the session. |
| AuthenticatedSession/$sessionID/ActiveRoles/$roleID | DELETE | none | Delete a role (specified by the $roleID variable) from the list of active roles for the authenticated session specified by the $sessionID variable. |
| AuthenticatedSession/$sessionID/AssumableRoles | GET | details | Query the roles which COULD be activated (assumed) by the authenticated session specified by the $sessionID variable. |
Attribute/Entity Nouns
| Resource / Noun | Method | Request/Response Content | Description |
| | | na | Invalid noun/verb combination - there is no way to create a context. |
| AuthenticatedSession/$sessionID/Context[?attr=$attrID[&attr=$attrIDn]...] | GET | <Context> element details | Return multiple entities. Currently returns all entities in the context. Might want to add a ?filter= or multiple ?entityID= parameters to limit the entities returned. |
| AuthenticatedSession/$sessionID/Context | PUT | <ContextChange> element details | Updates a context. May operate on multiple entities, using <EntityChange> child elements. |
| | | na | Invalid noun/verb combination - there is no way to delete a context. |
| AuthenticatedSession/$sessionID/Entity | POST | <Entity> element details | Creates a new entity. |
| AuthenticatedSession/$sessionID/Entity | GET | tbd | TBD. We could follow this with a ?<filter> construction to cause 0-* entities matching the filter to be returned. |
| | | na | Invalid noun/verb combination. Use the PUT on AuthenticatedSession/$sessionID/Context to update multiple entities with a single message. |
| AuthenticatedSession/$sessionID/Entity | DELETE | tbd | TBD. We could follow this with a ?<filter> construction to cause 0-* entities matching the filter to be deleted. |
| | | na | This is an invalid noun/verb combination. To create an entity, perform a POST on AuthenticatedSession/$sessionID/Entity. To create an attribute, perform a POST on AuthenticatedSession/$sessionID/Entity/$entityID/Attribute |
| AuthenticatedSession/$sessionID/entityID | GET | <Entity> element details | Get the authenticated entity ID for the session. |
| AuthenticatedSession/$sessionID/Entity/$entityID[?attr=$attrID[&attr=$attrIDn]...] | GET | <Entity> element details | Get an entity (specified by $entityID) in the authenticated session specified by the $sessionID variable. Optionally, a list of attributes to retrieve may be specified in the query component of the URL. |
| AuthenticatedSession/$sessionID/Entity/$entityID | PUT | <EntityChange> element details | Updates the specified entity. |
| AuthenticatedSession/$sessionID/Entity/$entityID | DELETE | none | Delete the entity (specified by $entityID) in the authenticated session specified by the $sessionID variable. |
| AuthenticatedSession/$sessionID/Entity/$entityID/Attribute | POST | <Attribute> element details | Creates a new attribute on the specified entity. |
| | | na | This is an invalid noun/verb combination. |
| AuthenticatedSession/$sessionID/Entity/$entityID/Attribute | PUT | tbd | TBD. We could have this pass an <EntityChange> element, but what's the point? |
| | | na | This is an invalid noun/verb combination. |
| | | na | This is an invalid noun/verb combination. To create an attribute, perform a POST on AuthenticatedSession/$sessionID/Entity/$entityID/Attribute. |
| AuthenticatedSession/$sessionID/Entity/$entityID/Attribute/$attrID | GET | <Attribute> element details | Reads the specified attribute from the specified entity. |
| AuthenticatedSession/$sessionID/Entity/$entityID/Attribute/$attrID | PUT | <AttributeChange> element details | Updates the specified attribute (typically adds or deletes values) on the specified entity. |
| AuthenticatedSession/$sessionID/Entity/$entityID/Attribute/$attrID | DELETE | none | Removes the specified attribute from the specified entity. |
Audit Log Nouns
| Resource / Noun | Method | Request/Response Content | Description |
| AuditLog | PUT | details | Log an audit record. |
Session Properties Nouns
| Resource / Noun | Method | Request/Response Content | Description |
| AuthenticatedSession/$sessionID/Properties[/$propertyName] | GET | details | Get one or ALL properties of an authenticated session. If $propertyName is specified, a single property is returned. Otherwise, all properties for the session are returned. |
| AuthenticatedSession/$sessionID/Properties/$propertyName | PUT | details | Set a property (specified by $propertyName) on an authenticated session. |
| AuthenticatedSession/$sessionID/Properties[/$propertyName] | DELETE | none | Delete one or ALL properties of an authenticated session. If $propertyName is specified, a single property is deleted. Otherwise, all properties are deleted. |
