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
isAllowedsubjects
subject
AllRESERVED 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
POSTRESERVED 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
  1. Client: accesses URI
  2. Service: validates URI, syntax checking, specified Context exists
  3. Service: get openptksession HTTP Query Parameter
    1. If Missing Parameter
      1. re-direct client to authenticate. Provide goto Query Parameter so that the Client can "return" to this scenario after they have been authenticated.
  4. Service: Get the unique identifier for the Session and validate it
    1. If Invalid Session
      1. re-direct client to authenticate. Provide goto Query Parameter so that the Client can "return" to this scenario after they have been authenticated.
  5. Service: Execute "search" using the specified Context
  6. Service: Post-Process the results, format for proper Representation
  7. Service: Return Representation
  8. Client: Post processes Representation
  9. 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
  1. Explicitly started at the Authenticator Resource
    • Listed the available Authenticators
    • Selected one of them
  2. 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

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