Projects‎ > ‎

RESTful Web Services

Architecture:

The OpenPTK configuration includes some behavior which is important to consider in the operation of these interactions. The following items are relevant:

The OpenPTK configuration will include the following Resource items which are important to the RESTful interaction:
- Authenticators
  This is a TOP level Resource. These are used to validate/prove that a client is who they say they are. There are different type and levels. The default Authenticator will be anonymous and have a level of 0 (zero). These resources are available at the root/base of the URI and are read-only. Clients can GET the available Authenticators and GET the details about a specific Authenticator. An Authenticator is needed to obtain a Session.
- Sessions
  This is a TOP level Resource. These are created when a client specifies an Authenticator and provides proper credentials (used by the Authenticator). After the Authenticator "authenticates" the client, a Session is created. The Session's unique identifier is returned to the client. The client will need to include this Session Id with every RESTful request. A client can create (GET) a Session. Clients can not view (GET) a list of Sessions. The client can read (GET) there own session. Clients can also invalidate (DELETE) there own Session.
- Contexts
  This is a TOP level Resource. These are used to specify the "type" of Subjects that will be managed. The Context uses the configuration file to define the Subject. The Context definition includes the type of back-end Service, Operations, and Attributes. A Context supports only one type of Subject. The client can read (GET) the available Contexts, view (GET) the details for a give Context. The Context is a read-only Resource.
- Subjects
  This is under the Context Resource. These refer to entries in the back-end Service. The client can List/search (GET) the existing Subjects, Read (GET) an individual Subject, Create (PUT/POST) a new Subject, Update (PUT) an existing Subject, and Delete (DELETE) a single Subject.
Context / Authenticator
- The Authenticators are defined in the Security section of the configuration file.
- Each Authenticator defines it's own "level" (0,1,2,3).
- The Context specifies what minimal Authenticator level it needs.

For more information about the configuration of the OpenPTK, see: Release 2.0 Sample XML file

Specifications:

The following information is describing the intended behaviour of the RESTful web service interaction with the RESTful server component for the OpenPTK.

State
- Application State
  - Client needs to manage
- Resource State
  - Managed by the Server
Representation:
- Use a distinct URI for each resource
- Client specifies type to return
  - URI encoding
    - append with type
  - HTTP request header:
    - Accept-Language
    - Accept
Uniform Interface
- Retrieve a representation of a resource:
  - GET
- Create a new resource:
  The client uses PUT when it is in charge of deciding which URI the new resource should have.
  The client uses POST when the server is in charge of deciding which URI the new resource should have.
  - PUT to a new URI
  - POST to an existing URI (creates a sub-resource)
- Modify an existing resource
  - PUT to an existing URI
- Delete an existing resource
  - DELETE

Properties:

These defined in the "Server" section of the openptk.xml file

Name	Description
`OPENPTKSESSIONID`	This is the name of the HTTP Cookie that is used by the "Server". This could should be created/managed by the ServeletFilter. Its value will be a `uniqueId` and will be used to store cached data about the user.

HTTP Methods to OpenPTK Operations:

	POST	GET	PUT	DELETE
`resource_type/`	Create Resource	Search Resources
`resource_type/{resource_id}`		Read Resource	Update Resource	Delete Resource

Action	OpenPTK Operation	HTTP method	example
List the Contexts	SEARCH	GET	/resources/contexts
View a Context	READ	GET	/resources/contexts/{context}
List the Subjects	SEARCH	GET	/resources/contexts/{context}/subjects
Create a new Subject	CREATE	POST	/resources/contexts/{context}/subjects
View a Subject	READ	GET	/resources/contexts/{context}/subjects/{subject}
Modify a Subject	UPDATE	PUT	/resources/contexts/{context}/subjects/{subject}
Delete a Subject	DELETE	DELETE	/resources/contexts/{context}/subjects/{subject}

HTTP Resources:

The HTTP RESTful syntax:

.../contexts
.../contexts/{id}
.../contexts/{id}/subjects
.../contexts/{id}/subjects/{id}
.../contexts/{id}/subjects/{id}/relationships/{id}/
.../contexts/{id}/subjects/{id}/views/{id}/
.../clients
.../clients/{id}
.../sessioninfo

Name	Description
`contexts`	An environment for a `subject`. The `contexts` define the `model`, `operations`, `service` and `definition`. The {id} is a "keyword" which is defined in the `openptk.xml` configuration file as a `Context` Element. The `context` Resource supports the following Operations List: `GET .../contexts` Read: `GET .../contexts/{id}`
`subjects`	A generic object that represents a record or entry in a repository within a given `context`. The `subject` Resource CAN support a combination of the following Operations Create: `POST .../subjects` Read: `GET .../subjects/{id}` Update: `PUT .../subjects/{id}` Delete: `DELETE .../subjects/{id}` Search: `GET .../subjects`
`relationships`	Business and technical "processes" that are related to a specific `subject`. The {id} is a "keyword" which is defined in the `openptk.xml` configuration file as part of a `model` assigned to the `context`. The applicable "operations", for a given `relationship` are dynamic and dependent on the implementation of the `model`. Each `relationship` can have its own sub-resource. Example: `.../relationships/{id`}
`views`	A "view" provides an aggregated set of information related to a `subject`. A `view` is a READ-ONLY Resource providing a convenient way of returning related information with a single `GET` request.
`clients`	Recognized (configured) users of the RESTful Web Service. Clients can support anonymous and authenticated end-users
`sessioninfo`	The End-User's current Session. Each Session has a unique identifier and type. If authenticated, the Session will also contain Principal information

Resources: contexts

Name	Subjects	Service	Repository
`Employee-LDAP-OpenDS`	Person	JNDI	LDAP
`Employee-JDBC-MySQL`	Person	JDBC	MySQL
`Locations-JDBC-MySQL`	Location	JDBC	MySQL

Resources: subjects

Name	Description
Person	An actual person with a set of attributes that are used to define their identity
Location	A physical location, such as an office, that has a set of attributes

Resources: Relationships

Relationships apply to Contexts that define a Model. The Model contains a set of Relationships.

Model	Relationship	Description	Syntax	Operations
`Employee`	`children`	`subjects` (children) that have a given `subject` declared as their parent	`.../subjects/{id}/relationships/children`	List/Search
`Employee`	`ancestors`	The `subject` that is declared as the parent	`.../subjects/{id}/relationships/ancestors`	Read
`Employee`	`siblings`	Other `subjects` that have a "common" parent (siblings)	`.../subjects/{id}/relationships/siblings`	List/Search
`Employee`	`location`	The reference (unique id) to an employee's physical office location	`.../subjects/{id}/relationships/location`	Read
`Customer`	`photo`	Multi-media content (mime-type) associated with a customer.	`.../subjects/{id}/relationships/photo`	Create, Read, Update, Delete

HTTP Response Codes:

Code	Name	Description
200	OK	Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request the response will contain an entity describing or containing the result of the action.
201	CREATED	The request has been fulfilled and resulted in a new resource being created.
204	NO_CONTENT	The server successfully processed the request, but is not returning any content.
400	BAD_REQUEST	For use when the client submits a PUT or POST request and the request cannot be processed by the server due to incorrect data in the request. This is intended to be a generic error message for a bad request and not intended to divulge securitye information to the user. Example would be if a required attribute is not sent with a create request, this response code should be sent to the client rather than a specific error message about the attribute which is missing
401	UNAUTHORIZED	Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided. The response must include a WWW-Authenticate header field containing a challenge applicable to the requested resource
403	FORBIDDEN	The request was a legal request, but the server is refusing to respond to it. Unlike a 401 Unauthorized response, authenticating will make no difference.
404	NOT_FOUND	The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.
500	INTERNAL_SERVER_ERROR	A generic error message, given when no more specific message is suitable.
503	SERVICE_UNAVAILABLE	The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.

All HTTP Methods could return the following codes:

401, UNAUTHORIZED
500, INTERNAL_SERVER_ERROR
503, SERVICE_UNAVAILABLE

Response Code to OpenPTK State map:

The OpenPTK RESTful Client API provides a Java interface to the OpenPTK Server. The API handles all the RESTful communications and provides access to "operation" via Java objects. The API uses an Output object to return results from Operations. The Output will contain a State based on the response from the OpenPTK Server (HTTP/REST Response). The following table outlines the possible State values.

REST/HTTP Response	OpenPTK State	Operation(s)	Examples
`200: OK`	`SUCCESS`	READ SEARCH PWDRESET	Read: returns attributes for the entry Search: search results, multiple entries PwdReset: returns new (reset) password
`201: CREATED`	`SUCCESS`	CREATE	Entry was created
`204: NO_CONTENT`	`SUCCESS`	UPDATE DELETE SEARCH PWDCHANGE PWDFORGOT	Update: entry was modified Delete: entry was removed Search: No entries were found PwdChange: password was changed.
`400: BAD_REQUEST`	`INVALID`	(ALL)	Something was "wrong" with the request
`401: UNAUTHORIZED`	`NOTAUTHENTICATED`	AUTHENTICATE	Credentials were not validated
`401: UNAUTHORIZED`	`NOTAUTHORIZED`	CREATE READ UPDATE DELETE PWDCHANGE PWDRESET PWDFORGOT	Decider has return a DENIED decision
`403: FORBIDDEN`	`FAILED`	CREATE UPDATE PWDCHANGE PWDRESET PWDFORGOT	Create: Entry already exists Update, PwdChange, PwdReset: could not update
`404: NOT_FOUND`	`NOTEXIST`	READ UPDATE DELETE PWDCHANGE PWDRESET PWDFORGOT	Entry does not exist
`500: INTERNAL_SERVER_ERROR`	`ERROR`	(ALL)	Mis-configured infrastructure
`503: SERVICE_UNAVAILABLER`	`ERROR`	(ALL)	Server not running

If the HTTP Response provides more information, that data will be placed in the Output status.

Resources to Response Code map:

Resource	Method	Success	Failure	Description
`/login`	POST	`200: OK`	`401: UNAUTHORIZED`	Invalid authentication
`/logout`	POST	`200: OK`		Logout and close a session
`/resources/*`	ALL		`401: UNAUTHORIZED`	Un-authorized operation (i.e. Deny from Decider) Un-authenticated (i.e. Loss of a session during an operation)
`/resources/contexts`	GET	`200: OK` `204: NO_CONTENT`		Get a list of `Contexts`
`/resources/contexts/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Read a `Contexts`
`/resources/contexts/{id}/subjects`	GET	`200: OK` `204: NO_CONTENT`		Search for `Subjects`
`/resources/contexts/{id}/subjects`	POST	`201: CREATED`	`400: BAD_REQUEST` `403: FORBIDDEN`	Create a `Subject`, may return 400 ... Problem with the attributes Entry already exists
`/resources/contexts/{id}/subjects/{id}`	GET	`200: OK`	`400: BAD_REQUEST` `404: NOT_FOUND`	Read a `Subject`
`/resources/contexts/{id}/subjects/{id}`	PUT	`200: OK`	`400: BAD_REQUEST` `403: FORBIDDEN` `404: NOT_FOUND`	Update a `Subject`
`/resources/contexts/{id}/subjects/{id}`	DELETE	`200: OK`	`404: NOT_FOUND`	Delete a `Subject`
`/resources/contexts/{id}/subjects/{id}/password/change`	PUT	`200: OK`	`400: BAD_REQUEST` `403: FORBIDDEN` `404: NOT_FOUND`	Change password for the `Subject`
`/resources/contexts/{id}/subjects/{id}/password/reset`	GET	`200: OK`	`404: NOT_FOUND`	Reset password for the `Subject`
`/resources/contexts/{id}/subjects/{id}/password/forgot/questions`	GET	`200: OK`	`404: NOT_FOUND`	Get the forgotten questions
`/resources/contexts/{id}/subjects/{id}/password/forgot/answers`	PUT	`200: OK`	`400: BAD_REQUEST` `404: NOT_FOUND`	Compared Questions and Answers for a match
`/resources/contexts/{id}/subjects/{id}/password/forgot/change`	PUT	`200: OK`	`400: BAD_REQUEST` `403: FORBIDDEN` `404: NOT_FOUND`	Change the password
`/resources/contexts/{id}/subjects/{id}/relationships`	GET	`200: OK` `204: NO_CONTENT`		List of `relationships`
`/resources/contexts/{id}/subjects/{id}/relationships/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a relationship item
`/resources/contexts/{id}/subjects/{id}/relationships/{id}`	POST	`201: CREATED`	`400: BAD_REQUEST` `403: FORBIDDEN`	Create a new relationship item
`/resources/contexts/{id}/subjects/{id}/relationships/{id}`	PUT	`200: OK`	`400: BAD_REQUEST` `404: NOT_FOUND`	Update a relationship item
`/resources/contexts/{id}/subjects/{id}/relationships/{id}`	DELETE	`200: OK`	`404: NOT_FOUND`	Delete a relationship item
`/resources/contexts/{id}/subjects/{id}/views`	GET	`200: OK`	`404: NOT_FOUND`	Get list of `Views`
`/resources/contexts/{id}/subjects/{id}/views/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Read a `View`
Resource	Method	Success	Failure	Description
`/resources/engine`	GET	`200: OK`	`404: NOT_FOUND`	Returns details about the engine
`/resources/engine/authenticators`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of authenticators
`/resources/engine/authenticators/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single authenticator
`/resources/engine/clients`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of clients
`/resources/engine/clients/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single client
`/resources/engine/contexts`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of contexts
`/resources/engine/contexts/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single context
`/resources/engine/converters`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of converters
`/resources/engine/converters/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single converter
`/resources/engine/models`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of models
`/resources/engine/models/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single models
`/resources/engine/sessions`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of sessions
`/resources/engine/sessions/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single session
`/resources/engine/sessions/{id}/caches`	GET	`200: OK` `204: NO_CONTENT`		Get a list of caches
`/resources/engine/sessions/{id}/caches/{id`}	GET	`200: OK`	`404: NOT_FOUND`	Get a single cache
`/resources/engine/statistics`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of Contexts
`/resources/engine/statistics/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get stats for a Context
Resource	Method	Success	Failure	Description
`/resources/clients`	GET	`200: OK` `204: NO_CONTENT`		Returns a list of clients
`/resources/clients/{id}`	GET	`200: OK`	`404: NOT_FOUND`	Get a single client
`/resources/sessioninfo`	GET	`200: OK`	`404: NOT_FOUND`	Get the session information (sessionId, sessionType, principalId). This will only provide access to a the session information that is associated with the OPENPTKSESSIONID Request cookie

Relationships:

Relationships are context (and model) specific. The table below describes the relationships associated to a Context that leverages a Model called Employee. The Employee Model contains these relationships:

`children`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/relationships/children`	GET	`200: OK`	`404: NOT_FOUND`	Get the list of `subjects` that have their "parent" equal to the `subject`
`ancestors`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/relationships/ancestors`	GET	`200: OK`	`404: NOT_FOUND`	Get the ordered list of `subjects` that describe the "parent" relationship starting from the `subject`
`siblings`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/relationships/siblings`	GET	`200: OK`	`404: NOT_FOUND`	Get the list of `subjects` that have the same "parent" as the `subject`
`location`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/relationships/location`	GET	`200: OK`	`404: NOT_FOUND`	Get the location record
`photo`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/relationships/photo`	POST	`201: CREATED`	`403: FORBIDDEN`	Create new `photo` entry
`/contexts/{id}/subjects/{id}/relationships/photo`	GET	`200: OK`	`404: NOT_FOUND`	Get the `photo` (octet-stream)
`/contexts/{id}/subjects/{id}/relationships/photo`	PUT	`200: OK`	`400: BAD_REQUEST` `403: FORBIDDEN` `404: NOT_FOUND`	Replace (update) `media` (octet-stream)
`/contexts/{id}/subjects/{id}/relationships/photo`	DELETE	`200: OK`	`404: NOT_FOUND`	Delete the `photo` that is stored

Views

Views are context (and model) specific, THEY ARE READ ONLY. The table below describes the views associated to a Context that leverages a Model called Employee. The Employee Model contains these views:

`address`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/views/address`	GET	`200: OK`	`404: NOT_FOUND`	Returns a "response" that contains the `Person` data merged with the `Location` data
`extended`	Method	Success	Failure	Description
`/contexts/{id}/subjects/{id}/view/extended`	GET	`200: OK`	`404: NOT_FOUND`	Returns a "response" that contains the `Person` data merged with the `Location` data and Lists for its `ancestors, siblings, children`

HTTP Query Parameters:

These parameters are "global" / "reserved" and may apply to all HTTP requests

Name	Resource(s)	Method	Description	Example
`return`	`subjects` `subject`	GET	RESERVED (not implemented) a separated list of attributes to return, uid and url are implied. The `uniqueId` and `uri` are automatically part of the returned data. If not set, all the Attributes defined in the AttrGroup for the Operation will be returned.	`return=firstname,lastname,email`
`search`	`subjects`	GET	There are two types of queries: basic and advanced. This keyword is used for the "basic" search. The value is a space separated list of words that are used by the Context's search algorithm	`search=Bob+Smith`
`offset`	`subjects`	GET	The offset value, index into the list of results. If not set, the value is `0` (zero)	`offset=20`
`quantity`	`subjects`	GET	Quantity of items to be returned. The value is less than or equal to the `length`. If not set, a default value from the Server Configuration is used. The server property used for default quantity is: results.quantity	`quantity=20`
`length`	All	All	RESERVED This is used to represent the entire length of a search result. This "keyword" is used within a response to a search	NA
`format`	All	All	RESERVED Representation should be specified by the client via the Http Header "Accept:" variable. Representation formats: `plain, html, xml, json`	format=json format=xml
`authn`	All	All	RESERVED	NA
`sort`	All	All	RESERVED	TBD
`session`	All	All	RESERVED It is planned to manage a user's session via a cookie (OPENPTKSESSION)	TBD
`query`	`subjects`	GET	RESERVED Future implementation of Advanced / Alternative query mechanism that can use arbitrary attribute names and values with specific look-up operators	TBD
`view`	`subjects` `subject`	GET	RESERVED FOR FUTURE USE HTTP header variables should be used to identity ow to represent results. The HEAD method should be used to obtain "meta data"	TBD
isAllowed	subjects subject	All	RESERVED FOR FUTURE USE Determine if the Request is allowed (not actually performed). An appropriate Response will indicate if the "actual" Request would be allowed or denied	TBD
operation	subjects subject	POST	RESERVED FOR FUTURE USE Allow for the overloading of the HTTP operation. Some clients / firewalls will not support HTTP operations like PUT and DELETE. The POST operation could be used with this parameter to inform the server that the operation should be processed with the specified operation	operation=put operation=delete

URI Naming convention:

Deployment	Description
`http(s)://{FQDN:PORT}/{deploy`}	Application root deployment context (rest),
RESTful URI path	Description
`/contexts`	List the Contexts
`/contexts/{id}`	Get the Context, use server default return attributes
`/contexts/{id}/subjects`	List the Subjects (for this Context), use server default query and return attributes
`/contexts/{id}/subjects/?return=lastcommafirst,title,email`	List the Subjects, return specified attributes (in order)
`/contexts/{id}/subjects/{id}`	Get a specific Subject (from the Context), use server default return attributes
`/contexts/{id}/subjects/{id}/?return=lastname;firstname;title`	Get a specific Person Resource, return the specified attributes (order is not imporant)
Punctuation character	Order important, use `comma` else use a `semi-colon`
`/contexts/{id}/subjects/{id}/roles/{id};{id}`	Semi-colon: Person Resource has two un-ordered Roles
`/contexts/{id}/subjects/{id}/children/{id},{id}`	Comma: Person has two childern, order by oldest first
`/contexts/{id}/?query=title+contains+engineer`	Space: use as a space character in a query
`/contexts/{id}/subjects.xml/contexts/{id}/subjects/{id}.json`	Period: Suffix used to indicate the format of either the input or output. Supported suffixes: .xml, .json, .plain, .html If a suffix is used, it will override the Header variable setting
URL query variables	Apply inputs to the algorithm:
`/contexts/{id}/?search=smith&offset=0&quantity=20`	search for "smith", result start at 0 return 20 items
`/contexts/{id}/?search=scott&return=firstname;lastname;email`	generic search for "scott" (server determines algo.) Return the firstname,lastname,email attributes

Search and Read prototype are functional leveraging JSR 311 with Jersey. Currently the prototype is only passing JSON formatted data. Testing with a JMaki table widget.

Packages / Classes:

Class Name	Description
`org.openptk.jaxrs`	This package contains "resources" for the RESTful web service. Implementation uses Project Jersey, JAX-RS (JSR-311)
`org.openptk.jaxrs.ContextsResource`	GET: listing of `contexts` path: `/contexts`
`org.openptk.jaxrs.ContextResource`	GET: read a single `context` path: `/contexts/{id`}
`org.openptk.jaxrs.SubjectsResource`	GET: listing of `subjects`, POST: creating new `subject` path: `/contexts/{id}/subjects`
`org.openptk.jaxrs.SubjectResource`	GET: read, PUT: update and DELETE: delete a single `subject` path: `/contexts/{id}/subjects/{id`}
`org.openptk.jaxrs.EngineResource`	GET: read a single `Engine` path: `/engine`
`org.openptk.jaxrs.SessionsResource`	GET: listing of `Sessions` path: `/engine/sessions`
`org.openptk.jaxrs.SessionResource`	GET: a single `Sessions` path: `/engine/sessions/{id`}
`org.openptk.jaxrs.CachesResource`	GET: listing of `Caches` path: `/engine/sessions/{id}/caches`
`org.openptk.jaxrs.CacheResource`	GET: a single `Cache` path: `/engine/sessions/{id}/caches/{id`}
`org.openptk.jaxrs.PasswordResource`	Password management for a `Subject` Change: `/contexts/{id}/subjects/{id}/password/change` Reset: `/contexts/{id}/subjects/{id}/password/reset` Forgot: `/contexts/{id}/subjects/{id}/password/forgot`
Class Name	Description
`org.openptk.structure`	This package and all it's classes define the "Structures". The "Structure" is a data model that is used to define arbitrary related information. Each `Structure` has a `name` and a `value`. It also supports a List of children and a List of peers.
`org.openptk.structure.StructureIF`	The `interface` for the Structure classes
`org.openptk.structure.Structure`	The `abstract class` for all application specific Structures
`org.openptk.structure.BasicStructure`	A `class` that `extends Structure`, provides a "basic" concrete class
`org.openptk.structure.StructureConverter`	A `static class` that provides "conversion" of a `Structure` to a specific output `String)` format. The formats include: `text/plain` `text/html` `application/json` `application/xml`

Use Cases:

These Use Cases define typical scenarios that will leverage the RESTful interface.

Get a List of Subjects from a Context

Description	Client wants to get a list of Subjects
Pre-Condition	The Client has a valid Session. A `Session` is defined by a HTTP Query Parameter: Example: `...&openptksession=a16d897d-2a38-43d8-9713-d0da5c780e4c` If the Client does not have a `Session`, or the session is invalid, the Client will be required to re-authenticate using the `Authenticator` specified by the `Context`: Example: `/sessions/?authenticate=FileIdPass`
Input	A HTTP GET Method is invoked using the known `Context` and `Subject` in the URI: `/contexts/test-ldap/subjects`
Output	The default Representation will be used (json). A collection of `Subjects` will be returned and it will contain URI's to access each individual entry.
Post-Condition	The Client's `Session` will have it's "last accessed" Date/Time update
Assumptions	The default search (none) will be used The default return attributes will be used
Steps	Client: accesses URI Service: validates URI, syntax checking, specified `Context` exists Service: get `openptksession` HTTP Query Parameter If Missing Parameter re-direct client to authenticate. Provide `goto` Query Parameter so that the Client can "return" to this scenario after they have been authenticated. Service: Get the unique identifier for the Session and validate it If Invalid Session re-direct client to authenticate. Provide `goto` Query Parameter so that the Client can "return" to this scenario after they have been authenticated. Service: Execute "search" using the specified `Context` Service: Post-Process the results, format for proper Representation Service: Return Representation Client: Post processes Representation Client: Displays data
Activity Diagram	needed

Authenticate a Client

Description	Client needs to Authenticate using a unique identifier and a password The Client gets to this RESTful service one of the following ways Explicitly started at the `Authenticator` Resource Listed the available `Authenticators` Selected one of them Got re-directed to the specific `Authenticator` from another RESTful web service method
Pre-Condition	The `Authenticator` has been implemented and has a means to "collect" Client data needed for authentication
Input	A HTTP POST Method is invoked with the proper HTTP Query Parameters Example: `/authenticators/FileIsPass/?id=thanks&password=Hello+World` Example: `/authenticators/FileIsPass/?id=thanks&password=Hello+World&openptksession=a16d897d-2a38-43d8-9713-d0da5c780e4c`
Output
Post-Condition
Assumptions
Steps

Authentication:

The OpenPTK Authenticator infrastructure will be extended to meet the RESTful requirements.

Resources:

Each type of data will be exposed as a resource.

Authenticator:

A list of Authenticators can be obtained prior to the creation of a Session. The returned list will be all of the Authenticators configured for the framework. From the list of available Authenticators, a specific Authenticator can be read. The client/user will use an authenticator the Session is created. The Authenticators resource is can be used to:

Identify the available Authenticators

The details of an Authenticator can be obtained to determine the required parameters required for its use when creating a session. The result will be:

The metadata which describes the requested Authenticator

List Authenticators

HTTP Method	`POST`
HTTP Session	none
HTTP Header	none

Syntax:

Authenticate	`/{deploy}/authenticators`

Examples:

http://www.example.com/openptk/rest/authenticators

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<authenticators>
   <authenticator name="Authn-IdPass" uri="http://www.example.com/openptk/rest/authenticators/Authn-IdPass" />
   <authenticator name="Authn-OpenSSO" uri="http://www.example.com/openptk/rest/authenticators/Authn-OpenSSO" />
</authenticators >

JSON

[
{url:"http://www.example.com/openptk/rest/authenticators/Authn-IdPass", name:"Authn-IdPass"},
{url:"http://www.example.com/openptk/rest/authenticators/Authn-OpenSSO", name:"Authn-OpenSSO"},
]

Read an Authenticator

HTTP Method	`POST`
HTTP Session	none
HTTP Header	none

Syntax:

Authenticate	`/{deploy}/authenticators/{authenticator}{`}

Examples:

http://www.example.com/openptk/rest/authenticators/Authn-IdPass
http://www.example.com/openptk/rest/authenticators/Authn-OpenSSO

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<context name="Authn-IdPass">
   <property name="name" value="value" />
   <property name="name2" value="value2" />
   ...
</context>

JSON

{
   name:"Authn-IdPass",
   properties:[
      {name:"name",value:"value"},
      {name:"name2",value:"value2"},   ...   ]
}

Top

Session:

After the user is authenticated (explicitly or anon) a Session will be created and managed by the Server processes. A unique key will be generated to identify the Session. This key will be returned to the client/user. The client/user will use the key when future HTTP requests are made. The Session will be used to:

Identify that the client has been authenticated
Store search results.
The client can request part of the search result set by supplying a offset and length with their query.

The key will need to be provided, by the client, with every request. The key can be exchanged via:

HTTP header variable
HTTP query parameter: &k=openptk_2009043021804007_Jt3iPXq4eW

Design Issue
The HTTP query parameter is the recommended approach in order to ensure simplicity for all users of the RESTful service.

Authenticate to get a OpenPTK Session

HTTP Method	`POST`
HTTP Session	none
HTTP Header	none

Syntax:

Authenticate	`/{deploy}/sessions/?authen={authenticator}&key1=value1&key2=value2&...`

Examples:

http://www.example.com/openptk/rest/sessions/?authen=Authn-IdPass&id=scott&pass=Hello+World
http://www.example.com/openptk/rest/sessions/?authen=Authn-IdPass&id=scott&encrypted=FSefsdf4f3gtwdfs==
http://www.example.com/openptk/rest/sessions/?authen=Authn-OpenSSO&token=dgsertgsertevseresgsdg

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<session>2009043021804007_Jt3iPXq4eW"</session>

JSON

{
   session:"2009043021804007_Jt3iPXq4eW"
}

Context

Operations	Search	Read

Search for available Contexts

HTTP Method	`GET`
HTTP Session	none
HTTP Header	none

Syntax:

Default search	`/{deploy}/contexts`

Examples:

http://www.example.com/openptk/rest/contexts

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<contexts>
   <context name="Person-SunIdm-SPML1" uri="http://www.example.com/openptk/rest/contexts/Person-SunIdm-SPML1" />
   <context name="Person-SunIdm-SPML2" uri="http://www.example.com/openptk/rest/contexts/Person-SunIdm-SPML2" />
   <context name="Person-SunIdm-SPE" uri="http://www.example.com/openptk/rest/contexts/Person-SunIdm-SPE" />
   <context name="Person-OpenDS-JNDI" uri="http://www.example.com/openptk/rest/contexts/Person-OpenDS-JNDI" />
   <context name="Person-MySQL-JDBC" uri="http://www.example.com/openptk/rest/contexts/Person-MySQL-JDBC" />
   <context name="Person-Hybrid" uri="http://www.example.com/openptk/rest/contexts/Person-Hybrid" />
   <context name="Role-SunIdm-SPML1" uri="http://www.example.com/openptk/rest/contexts/Role-SunIdm-SPML1" />
</contexts>

JSON

[
{url:"http://www.example.com/openptk/rest/contexts/Person-SunIdm-SPML1", name:"Person-SunIdm-SPML1"},
{url:"http://www.openptk.org/openptk/rest/contexts/Person-SunIdm-SPML2", name:"Person-SunIdm-SPML2"},
{url:"http://www.openptk.org/openptk/rest/contexts/Person-SunIdm-SPE", name:"Person-SunIdm-SPE"},
{url:"http://www.openptk.org/openptk/rest/contexts/Person-OpenDS-JNDI", name:"Person-OpenDS-JNDI"},
{url:"http://www.openptk.org/openptk/rest/contexts/Person-MySQL-JDBC", name:"Person-MySQL-JDBC"},
{url:"http://www.openptk.org/openptk/rest/contexts/Person-Hybrid", name:"Person-Hybrid"},
{url:"http://www.openptk.org/openptk/rest/contexts/Role-SunIdm-SPML1", name:"Role-SunIdm-SPML1"}
]

Read a specific Context

HTTP Method	`GET`
HTTP Session	none
HTTP Header	none

Syntax:

Default search	`/{deploy}/contexts/{context`}

Examples:

http://www.openptk.org/openptk/rest/contexts/Person-SunIdm-SPML1
http://www.openptk.org/openptk/rest/contexts/Person-OpenDS-JNDI

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<context name="idm-spml1">
   <property name="definition" value="Person" />
   <property name="connection" value="SunSPML1" />
   <property name="association" value="SPML1" />
   <property name="context.description" value="Person to Sun Identity Manager using SPML1" />
   <property name="operation.classname" value="org.openptk.provision.spi.operations.SpmlSunOperations" />
   ...
</context>

JSON

{
   name:"idm-spml1",
   properties:[
      {name:"definition",value:"Person"},
      {name:"connection",value:"SunSPML1"},
      {name:"association",value:"SunSPML1"},
      {name:"context.description",value:"Person to Sun Identity Manager using SPML1"},
      {name:"operation.classname",value:"org.openptk.provision.spi.operations.SpmlSunOperations"},
   ]
}

Subject

This Resource matches the OpenPTK Subject

Operations	Meta	Search	Create	Read	Update	Delete

Subject Meta data

Return Meta data about the Subject Resource and Representations

HTTP Method	`HEAD`
HTTP Session	none
HTTP Header	none

Syntax

Use HEAD method	`/contexts/{context}/subjects`
List of Subect Properties	`/contexts/{context}/subjects/?meta=properties`
Available Subject Attributes	`/contexts/{context}/subjects/?meta=attributes`

Examples:

http://www.openptk.org/openptk/rest/contexts/Person-SunIDM-SPML1/subjects/?meta=properties
http://www.openptk.org/openptk/rest/contexts/Person-SunIDM-SPML1/subjects/?meta=attributes

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<person>
   <attributes>
      <attribute name="uniqueid">
         <properties><property name="required" value="true"/></properties>
      </attribute>
      <attribute name="firstname">
         <properties><property name="required" value="true"/></properties>
      </attribute>
      <attribute name="lastname">
         <properties><property name="required" value="true"/></properties>
      </attribute>
      <attribute name="email"/>
      <attribute name="roles">
         <properties><property name="allowMultiValue" value="true"/></properties>
      </attribute>
      ...
   </attributes>
   <properties>
      <property .../>
   </properties>
</person>

JSON

{
   attributes:[
      { uniqueid:[{required:"true"},{minlength:"4"},{maxlength:"8"}] },
      { firstname:[{required:"true"},{minlength:"2"},{maxlength:"24"}] },
      { lastname:[{required:"true"}] },
      { lastcommafirst:[] },
      { email:[] },
      { roles:[{allowMultiValue:"true""}] }
   ]
   properties:[
      {name:"",value:""},
      {name:"",value:""}
   ]
}

Search for Subjects or a Subject

Returns a collection of Subject Objects (Subjects) in the specified format.

OpenPTK Operation	`SEARCH`
HTTP Method	`GET`
HTTP Session	none
HTTP Header	none

Syntax:

The default search:

uses a server-side configured search algorithm
attributes to return.
view (default)
format (default)

Default search, default Attributes	`/contexts/{context}/people`
Use query, default Attributes	`/contexts/{context}/people/?search={query+phrase`}
Use query, specified (un-ordered) Attributes	`/contexts/{context}/subjects/?search={query+phrase}&return={attr};{attr};{attr`}
Use query, use specified representation	`/contexts/{context}/subjects/?search={query+phrase}&format=xml`
Use query, sub-set of list	`/contexts/{context}/subjects/?search={query+phrase}&offset={offset}&length={length`}

Examples:

http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/?search=Sally
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/?return=lastname;firstname;email
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/?search=firstname+contains+Bob&return=lastcommafirst;title&format=json
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/?search=Scott&offset=40&length=20

Representations:

XML

<?xml version="1.0" standalone='yes'?>
<people>
   <person href="http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/thanks" name="Hanks, Tom"/>
   <person href="http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/jwayne" name="Wayne, John"/>
   ...
</people>

JSON

[
{url:"http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/thanks", name:"Hanks, Tom"},
{url:"http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/jwayne", name:"Wayne, John"},
...
]

Create a Subject

Read a single Subject

Returns a single Subject (Object) in the specified Representation.

OpenPTK Operation	`READ`
HTTP Method	`GET`
HTTP Session	none
HTTP Header	none

Parameters:

Name	Description	Example
`view`	What view should be used to return the data. example: `meta` would return information about the interface / data representation. The default view is `default`. If not set, the default is used.	`view=extended` `view=meta`
`return`	a separated list of attributes to return, uid and url are implied. The `uniqueId` and `uri` are automatically part of the returned data.	`return=firstname+lastname+email`
`format`	a valid format type: `xhtml,xml,json`	`format=json`
`authn`	Authentication type: `param,opensso`	`authn=opensso`

Syntax:

Default Attributes	`/contexts/{context}/subjects/{id`}
Specified (un-ordered) Attributes	`/contexts/{context}/subjects/{id}/?return={attr};{attr};{attr`}
Default Attributes, specified representation	`/contexts/{context}/subjects/{id}/?format=xml`

Examples:

http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/jwayne
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/jwayne/?return=lastname;firstname;email
http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/jwayne/?return=lastcommafirst;title&format=json

Representation:

XML

<?xml version="1.0" standalone='yes'?>
<person>
   <attributes>
      <attribute name="uri" value="http://www.openptk.org/rest/contexts/idm-spml1/subjects/thanks" />
      <attribute name="uniqueid" value="thanks"/>
      <attribute name="firstname">
         <values><value>Tom<value/><values>
      </attribute>
      <attribute name="lastname" value="Hanks"/>
      <attribute name="email" value="tom@hanks.com"/>
      <attribute name="roles">
         <values>
            <value>Admin</value>
            <value>Business</value>
         </values>
      </attribute>
      ...
   </attributes>
</person>

JSON

{
   url:"http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/thanks",
   uniqueid:"thanks",
   firstname:"Tom",
   lastname:"Hanks",
   lastcommafirst:"Hanks, Tom",
   email:"tom@hanks.com",
   roles:[
      {uniqueid:"Admin",url:"http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/Admin"},
      {uniqueid:"Busines",url:"http://www.openptk.org/openptk/rest/contexts/idm-spml1/subjects/Business"}
   ]
}

Update a specific Subject

Delete a specific Subject

Client

Read the users Client Session

Returns the users's Session data, based on a specific Client

OpenPTK Operation	`READ`
HTTP Method	`GET`
HTTP Session	ANON or USER
HTTP Header	none

Parameters:

Name	Description	Example

Syntax:

Default Attributes	`/clients/{id}/session`

Examples:

http://localhost/openptk/resources/clients/myclient/session

Representation ANON:

XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <uri type="string">http://localhost:8080/openptk/resources/clients/apitest/session</uri>
   <uniqueId type="string">605cade0-8b0b-49b5-acb3-41227d3f7187</uniqueid>
   <type type="string">ANON</type>
   <principal>
      </uniqueId type="string">
      </contextId type="string">
   </principal>
</response>

JSON

{
    "response" : {
        "uri" : "http:\/\/localhost:8080\/openptk\/resources\/clients\/apitest\/session",
        "sessionId" : "12beb429-116b-4edb-9ded-f89e0986ab10",
        "type" : "ANON",
        "principal" : {
            "uniqueId" : null,
            "contextId" : null
        }
    }
}

Representation USER:

XML

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <uri type="string">http://localhost:8080/openptk/resources/clients/apitest/session</uri>
   <uniqueId type="string">605cade0-8b0b-49b5-acb3-41227d3f7187</uniqueid>
   <type type="string">USER</type>
   <principal>
      <uniqueId type="string">bsmith</uniqueId>
      <contextId type="string">Employee-JNDI-OpenPD</contextId>
   </principal>
</response>

JSON

{
    "response" : {
        "uri" : "http:\/\/localhost:8080\/openptk\/resources\/clients\/apitest\/session",
        "sessionId" : "12beb429-116b-4edb-9ded-f89e0986ab10",
        "type" : "USER",
        "principal" : {
            "uniqueId" : "bsmith",
            "contextId" : "Employee-JNDI-OpenDS"
        }
    }
}

Comments

Page authors

RESTful Web Services

Architecture:

Specifications:

Properties:

HTTP Methods to OpenPTK Operations:

HTTP Resources:

Resources: contexts

Resources: subjects

Resources: Relationships

HTTP Response Codes:

Response Code to OpenPTK State map:

Resources to Response Code map:

Relationships:

Views

HTTP Query Parameters:

URI Naming convention:

Packages / Classes:

Use Cases:

Get a List of Subjects from a Context

Authenticate a Client

Authentication:

Resources:

Authenticator:

Session:

Context

Subject

Client