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
- Resource State
- Representation:
- Use a distinct URI for each resource
- Client specifies type to return
- URI encoding
- HTTP request header:
- Uniform Interface
- Retrieve a representation of a resource:
- 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
- Delete an existing resource
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"},
]
|
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
|
Context
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
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"},
...
]
|
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:
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"
}
}
}
|
|