Projects‎ > ‎

RESTful API


CREATE operation

HTTP POST
The creation of a new Subject, in a Context, is accomplished using a pre-defined Structure.  The Structure has the following format:
  • subject
    • attributes
      • attribute1
        • value1
        • valueN
      • attributeN
The Structure is automatically defined by the OpenPTK Client API and then sent to the server's RESTful interface using an XML encoded string that represents the Structure. The Structure can be manually created or formatted by an AJAX application and then encoded using a JSON formatted string.


JSON example:


"subject" : 
   { "attributes" : 
      { "lastname" : "User", 
        "title" : "REST User", 
        "firstname" : "Curl", 
        "telephone" : "123-456-7890", 
        "email" : "curl@openptk.org"
      }
   }
}

XML example:


<subject>
   <attributes>
      <lastname type="string">User</lastname>
      <title type="string">REST User</title>
      <firstname type="string">Curl</firstname>
      <telephone type="string">123-456-7890</telephone>
      <email type="string">curl@openptk.org</email>
   </attributes>
</subject>


READ operation

HTTP GET
A successful read operation will return an encoded String, using JSON or XML, representing a single Structure from a Context.
  • response
    • uri
    • state
    • status
    • subject
      • uniqueid
      • attributes
        • attribute1
          • value1
          • valueN
        • attributeN
    • resources
      • resource1
        • description
        • uri
      • resourceN

JSON example:


{
   "response" : {
      "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/ja1324",
      "state" : "SUCCESS",
      "status" : "Entry found",
      "subject" : {
         "uniqueid" : "ja1324",
         "attributes" : {
            "manager" : "sa15346",
            "location" : "loc35",
            "forgottenPasswordAnswers" : ["","",""],
            "lastname" : "Andrews",
            "firstname" : "John",
            "title" : "Title",
            "organization" : "Corporate Executive",
            "email" : "John.Andrews@openptk.com",
            "roles" : "Employee",
            "forgottenPasswordQuestions" : ["Mothers Maiden Name","City you were born","Last 4 digits of Frequent Flyer"],
            "telephone" : "303-191-5506",
            "fullname" : "John Andrews",
            "lastcommafirst" : "Andrews, John"
         }
      },
      "resources" : {
         "resource" : {
            "description" : "Relationships",
            "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/ja1324\/relationships"
         },
         "resource" : {
            "description" : "Views",
            "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/ja1324\/views"
         }
      }
   }
}

2.2:

{
"uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324",
"state":"SUCCESS",
"status":"Entry found",
"subject":{
"uniqueid":"ja1324",
"attributes":{
"manager":"sa15346",
"location":"loc35",
"forgottenPasswordAnswers":["","",""],
"lastname":"Andrews",
"firstname":"John",
"title":"Title",
"organization":"Corporate Executive",
"email":"John.Andrews@openptk.com",
"roles":"Employee",
"forgottenPasswordQuestions":[
"Mothers Maiden Name",
"City you were born",
"Last 4 digits of Frequent Flyer"
],
"telephone":"303-191-5506",
"fullname":"John Andrews",
"lastcommafirst":"Andrews, John"
}
},
"resources":[{
"description":"Relationships",
"uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324/relationships"
},{
"description":"Views",
"uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324/views"
}]
}

XML example:

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/ja1324</uri>
  <state type="string">SUCCESS</state>
  <status type="string">Entry found</status>
  <subject>
    <uniqueid type="string">ja1324</uniqueid>
    <attributes>
      <manager type="string">sa15346</manager>
      <location type="string">loc35</location>
      <forgottenPasswordAnswers type="string">
        <values>
          <value></value>
          <value></value>
          <value></value>
        </values>
      </forgottenPasswordAnswers>
      <lastname type="string">Andrews</lastname>
      <firstname type="string">John</firstname>
      <title type="string">Title</title>
      <organization type="string">Corporate Executive</organization>
      <email type="string">John.Andrews@openptk.com</email>
      <roles type="string">Employee</roles>
      <forgottenPasswordQuestions type="string">
        <values>
          <value>Mothers Maiden Name</value>
          <value>City you were born</value>
          <value>Last 4 digits of Frequent Flyer</value>
        </values>
      </forgottenPasswordQuestions>
      <telephone type="string">303-191-5506</telephone>
      <fullname type="string">John Andrews</fullname>
      <lastcommafirst type="string">Andrews, John</lastcommafirst>
    </attributes>
  </subject>
  <resources>
    <resource>
      <description type="string">Relationships</description>
      <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/ja1324/relationships</uri>
    </resource>
    <resource>
      <description type="string">Views</description>
      <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/ja1324/views</uri>
    </resource>
  </resources>
</response>

2.2

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <uri type="string">http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324</uri>
    <state type="string">SUCCESS</state>
    <status type="string">Entry found</status>
    <subject>
        <uniqueid type="string">ja1324</uniqueid>
        <attributes>
            <manager type="string">sa15346</manager>
            <location type="string">loc35</location>
            <forgottenPasswordAnswers type="string">
                <value/>
                <value/>
                <value/>
            </forgottenPasswordAnswers>
            <lastname type="string">Andrews</lastname>
            <firstname type="string">John</firstname>
            <title type="string">Title</title>
            <organization type="string">Corporate Executive</organization>
            <email type="string">John.Andrews@openptk.com</email>
            <roles type="string">Employee</roles>
            <forgottenPasswordQuestions type="string">
                <value>Mothers Maiden Name</value>
                <value>City you were born</value>
                <value>Last 4 digits of Frequent Flyer</value>
            </forgottenPasswordQuestions>
            <telephone type="string">303-191-5506</telephone>
            <fullname type="string">John Andrews</fullname>
            <lastcommafirst type="string">Andrews, John</lastcommafirst>
        </attributes>
    </subject>
    <resources type="structure">
        <resource>
            <description type="string">Relationships</description>
            <uri type="string">http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324/relationships</uri>
        </resource>
        <resource>
            <description type="string">Views</description>
            <uri type="string">http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/ja1324/views</uri>
        </resource>
    </resources>
</response>


UPDATE operation

HTTP PUT

  • subject
    • attributes
      • attribute1
        • value1
        • valueN
      • attributeN

JSON example


   "subject" : { 
      "attributes" : { 
         "password" : "Passw0rd" 
      }
   }
}

XML example


<subject>
   <attributes>
      <password type="string">Passw0rd</password>
   </attributes>
</subject>


DELETE operation

HTTP DELETE



SEARCH operation

HTTP GET

  • response
    • uri
    • state
    • length
    • offset
    • quantity
    • results
      • subject1
        • uri
        • uniqueid
        • attributes
          • attribute1
            • value1
            • valueN
          • attributeN
      • subjectN

JSON example:


{
    "response" : {
        "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/",
        "state" : "SUCCESS",
        "length" : 3,
        "offset" : 0,
        "quantity" : 3,
        "results" : [
            {
                "subject" : {
                    "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/sa15346",
                    "uniqueid" : "sa15346",
                    "attributes" : {
                        "title" : "Title",
                        "email" : "Scott.Anderson@openptk.com",
                        "lastcommafirst" : "Anderson, Scott"
                    }
                }
            },
            {
                "subject" : {
                    "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/sfehrman",
                    "uniqueid" : "sfehrman",
                    "attributes" : {
                        "title" : null,
                        "email" : "Scott.Fehrman@openptk.org",
                        "lastcommafirst" : "Fehrman, Scott"
                    }
                }
            },
            {
                "subject" : {
                    "uri" : "http:\/\/localhost:8080\/openptk-server\/resources\/contexts\/LDAP\/subjects\/st82921",
                    "uniqueid" : "st82921",
                    "attributes" : {
                        "title" : "Title",
                        "email" : "Scott.Townsend@openptk.com",
                        "lastcommafirst" : "Townsend, Scott"
                    }
                }
            }
        ]
    }
}

2.2

{
   "uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects",
   "state":"SUCCESS",
   "length":3,
   "offset":0,
   "quantity":3,
   "results":[{
      "uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/sa15346",
      "uniqueid":"sa15346",
      "attributes":{
         "title":"Title",
         "email":"Scott.Anderson@openptk.com",
         "lastcommafirst":"Anderson, Scott"
      }
   },{
      "uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/sfehrman",
      "uniqueid":"sfehrman",
      "attributes":{
         "title":null,
         "email":"Scott.Fehrman@openptk.org",
         "lastcommafirst":"Fehrman, Scott"
      }
   },{
      "uri":"http://localhost:8080/openptk-server/resources/contexts/Employees-Embed-JDBC/subjects/st82921",
      "uniqueid":"st82921",
      "attributes":{
         "title":"Title",
         "email":"Scott.Townsend@openptk.com",
         "lastcommafirst":"Townsend, Scott"
      }
   }]
}


XML example:


<?xml version="1.0" encoding="UTF-8"?>
<response>
  <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/</uri>
  <state type="string">SUCCESS</state>
  <length type="integer">3</length>
  <offset type="integer">0</offset>
  <quantity type="integer">3</quantity>
  <results>
    <subject>
      <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/sa15346</uri>
      <uniqueid type="string">sa15346</uniqueid>
      <attributes>
        <title type="string">Title</title>
        <email type="string">Scott.Anderson@openptk.com</email>
        <lastcommafirst type="string">Anderson, Scott</lastcommafirst>
      </attributes>
    </subject>
    <subject>
      <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/sfehrman</uri>
      <uniqueid type="string">sfehrman</uniqueid>
      <attributes>
        <title type="string" />
        <email type="string">Scott.Fehrman@openptk.org</email>
        <lastcommafirst type="string">Fehrman, Scott</lastcommafirst>
      </attributes>
    </subject>
    <subject>
      <uri type="string">http://localhost:8080/openptk-server/resources/contexts/LDAP/subjects/st82921</uri>
      <uniqueid type="string">st82921</uniqueid>
      <attributes>
        <title type="string">Title</title>
        <email type="string">Scott.Townsend@openptk.com</email>
        <lastcommafirst type="string">Townsend, Scott</lastcommafirst>
      </attributes>
    </subject>
  </results>
</response>


JSON Options


openptk.xml


   <Converters>
      <Converter type="json" classname="org.openptk.structure.JsonConverter"/>
      <Converter type="xml" classname="org.openptk.structure.XmlConverter">
         <Structures>
            <Structure id="forgottenPasswordAnswers">
               <Properties>
                  <Property name="multivalue" value="true"/>
               </Properties>
            </Structure>
            <Structure id="forgottenPasswordQuestions">
               <Properties>
                  <Property name="multivalue" value="true"/>
               </Properties>
            </Structure>
            <Structure id="roles">
               <Properties>
                  <Property name="multivalue" value="true"/>
               </Properties>
            </Structure>
            <Structure id="contexts">
               <Properties>
                  <Property name="multivalue" value="true"/>
               </Properties>
            </Structure>
         </Structures>
      </Converter>
      <Converter type="html" classname="org.openptk.structure.HtmlConverter"/>
      <Converter type="plain" classname="org.openptk.structure.PlainConverter"/>
   </Converters>