User Tools

Site Tools


ldapbook_api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
ldapbook_api [2010/10/19 21:31]
admin
ldapbook_api [2010/10/19 21:31] (current)
admin
Line 1: Line 1:
 +====== CloudFace API ======
  
 +Integrate the [[http://​entic.net/​CF|CloudFace]] into your own applications. No custom API's to write or learn. Your user's address book can be accessed directly using the LDAP protocol.
 +
 +We've collected a few sample sites that show the use of the (native) LDAP API in several different languages:
 +
 +  * [[http://​www.linuxjournal.com/​article/​6988|Python]]
 +  * [[http://​blogs.sun.com/​marginNotes/​entry/​ldap_basics_with_php|PHP]]
 +  * [[http://​www.tutorialspoint.com/​ruby/​ruby_ldap.htm|Ruby]]
 +  * [[http://​cwiki.apache.org/​confluence/​display/​DIRAPI/​Index|Java]]
 +  * C [[http://​www.mozilla.org/​directory/​csdk-docs|Mozilla]] [[http://​www.yolinux.com/​TUTORIALS/​LinuxTutorialLDAP-SoftwareDevelopment.html|OpenLDAP]]
 +===== Schema =====
 +
 +For the most part we've tried to use the RFC standard schema attributes in defining the address book. But we extend it with a few additional items, see Schema Extension below. In addition, we make some special considerations for managing the attributes homePostalAddress,​ dateOfBirth,​ and the jpegPhoto.
 +
 +  * The **homePostalAddress** attribute is a $ delimited address list - which we also split and populate ("​sync"​) to their corresponding attributes: homeStreet, homeCity, homeState, homeCountry,​ and homePostalCode. When representing this attribute, the $ should be converted to new lines. For e.g. the //312 S. Bascom$Santa Clara$CA$94082$USA//​ homePostalAddress value in LDAP should be represented as:
 +
 +  312 S. Bascom ​   (homeStreet)
 +  Santa Clara      (homeCity)
 +  CA               ​(homeState)
 +  94082            (homePostalCode)
 +  USA              (homeCountry)
 +
 +
 +  * The **dateOfBirth** attribute (values are of YYYY-MM-DD format) is constructed from three additional attributes (all of which can have numerical values):
 +
 +  birthYear
 +  birthMonth
 +  birthDay
 +  ​
 +Your code should keep these attributes dateOfBirth and homePostalAddress in sync with their birth* and the home* attributes.
 +
 +In addition, the **jpegPhoto** attribute has some special requirements. In addition to the RFC standard 1.3.6.1.4.1.1466.115.121.1.28 syntax, we also allow this attribute to contain a URL of the photo resource. This URL can be of the form http or file reference.
 +
 +===== Schema Extension =====
 +
 +Our registered base OID is: 1.3.6.1.4.1.27867. LDAPBook makes some minor extensions to the default schema:
 +==== attributeTypes:​ 1.3.6.1.4.1.27867.1.1.X ====
 +
 +People Objects
 +
 +^ OID      ^ Name       ^ Syntax ​        ^ Notes ^
 +| 1.3.6.1.4.1.27867.1.1.1 ​   | imhandle ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.5 ​   | tag | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.6 ​  | homeStreet | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.7 ​ | homeCity | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.8 ​ | homeState | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.9 ​ | homePostalCode | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.10 ​ | homeCountry | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.11 | birthYear | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.12 | birthMonth | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.13 | birthDay | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.14 | dateOfBirth | 1.3.6.1.4.1.1466.115.121.1.15 | |
 +| 1.3.6.1.4.1.27867.1.1.57 ​   | mediaURL ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | From Event Objects |
 +
 +Event Objects
 +
 +^ OID      ^ Name       ^ Syntax ​        ^ Notes ^
 +| 1.3.6.1.4.1.27867.1.1.50 ​   | dateOfEvent ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.51 ​   | eventDay ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.52 ​   | eventMonth ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.53 ​   | eventYear ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.54 ​   | longitude ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.55 ​   | latitude ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.56 ​   | eventPrivate ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +| 1.3.6.1.4.1.27867.1.1.57 ​   | mediaURL ​    | 1.3.6.1.4.1.1466.115.121.1.15 ​       | |
 +
 +Place Objects
 +
 +^ OID      ^ Name       ^ Syntax ​        ^ Notes ^
 +| 1.3.6.1.4.1.27867.1.1.100 ​   | placeId ​    | 1.3.6.1.4.1.1466.115.121.1.27 ​       | |
 +
 +
 +==== objectClass:​ 1.3.6.1.4.1.27867.1.2.X ====
 +
 +
 +^ OID      ^ Name       ^ MUST       ^ MAY ^
 +| 1.3.6.1.4.1.27867.1.2.4 ​   | tag     | mail $ cn        |
 +| 1.3.6.1.4.1.27867.1.2.1 ​   | pabPerson ​    ​| ​      | c $ otherMailbox $ imhandle $ telephone-office2 $ homeStreet $ homeCity $ homeState $ homePostalCode $ homeCountry $ birthYear $ birthMonth $ birthDay $ dateOfBirth $ mediaURL |
 +| 1.3.6.1.4.1.27867.1.2.5 ​   | event     | dateOfEvent ​  | cn $ description $ longitude $ latitude $ eventDay $ eventMonth $ eventYear $ jpegPhoto $ eventPrivate $ mediaURL |
 +| 1.3.6.1.4.1.27867.1.2.6 ​   | place     | cn    | labeledURI $ mail $ description $ longitude $ latitude $ jpegPhoto |
 +
 +
 +===== Connecting/​BIND =====
 +
 +Anonymous lookups to the public are disabled. You can connect to the LDAP server using the [[http://​wiki.entic.net/​doku.php?​id=ldapbook#​client_configuration|full DN]] of the user or you can lookup users with certain criteria to determine DN. This lookup requires special access. To request this feature be added to your account, please contact us. You'll need to have a valid account with [[http://​entic.net/​register|Entic.net]].
 +===== Contacts =====
 +
 +All contacts created using the [[http://​entic.net/​CF|CloudFace]] interface get the following objectClass added:
 +
 +  * top
 +  * person
 +  * organizationalPerson
 +  * inetOrgPerson
 +  * pabPerson
 +
 +The RDN for the contacts use the **cn** attribute. The contacts are stored under the **uid=<​username>,​ ou=People, o=entic.net** branch.
 +
 +===== Tags =====
 +
 +Each contact can have one or more tags assigned to it. Tags are **one or two word** descriptions that describe that contact. We use the **description** attribute (OID: 2.5.4.13) to store the tag name in LDAP. You can assign the same tag name to multiple contacts.
 +
 +
 +====== HTTP REST API ======
 +
 +Most of the access to LDAPBook will be done using the LDAP protocol itself, but we extend this with a few additional features.
 +
 +The base URL to access the API is: https://​api.entic.net/​api
 +HTTP Basic authentication should be used to connect. The user name is formatted as: user@DOMAIN (the Domain the API should be set with). The password is a MD5 hash.
 +
 +The Content-Type header should be set to  **application/​xml** for POST and PUT requests.
 +==== Registration ====
 +
 +=== Request ===
 +
 +**__Required__:​ name, uid, and password**
 +**__Optional__:​ mail, debug, subscribe, and domain**
 +
 +  * Password and name require a minimum length of 5 characters. Login should be alphanumeric with a minimum of 3 characters. ​
 +  * If mail is omitted, a mail address of uid@DOMAIN will be generated. ​
 +  * Domain defaults to **entic.net**.
 +  * If debug is specified, do a validation check and don't save to database.
 +  * If domain is **entic.net** and subscribe is specified, subscribe user to mailing list.
 +
 +  POST https://​entic.net/​api/​account/​register
 +  ​
 +  <​account>​
 +    <​name>​Full Name</​name>​
 +    <​mail>​asdf@sadf.com</​mail>​
 +    <​uid>​login</​uid>​
 +    <​password>​pass</​password>​
 +    <​domain>​entic.net</​domain>​
 +    <​debug/>​
 +    <​subscribe/>​
 +  </​account>​
 +
 +
 +
 +=== Response ===
 +
 +HTTP/1.1 Status response codes with message
 +  400 on validation failures
 +  <​account>​
 +    <​result>​error</​result>​
 +    <​message>​uid:​ too short</​message>​
 +  </​account>​
 +  ​
 +  201 on success, with this response body
 +  <​account>​
 +    <​result>​success</​result>​
 +  </​account>​
 +   
 +==== Location ====
 +
 +=== Request ===
 +
 +**__Required__:​ search**
 +
 +  POST https://​entic.net/​api/​search
 +  ​
 +  <​location>​
 +    <​lat></​lat>​
 +    <​lon></​lon>​
 +    <​search>​string</​search>​
 +  </​account>​
 +  ​
 +=== Response ===
 +
 +  201 on success, with this response body
 +  <​location>​
 +    <​result>​success</​result>​
 +    <​matches></​matches>​
 +  </​location>​
 +</​account>  ​
 +
 +==== Usage ====
 +
 +=== Request ===
 +
 +**__Required__:​ uid**
 +**__Optional__:​ debug, and domain**
 +
 +  * Login should be alphanumeric with a minimum of 3 characters. ​
 +  * If domain is not specified, it defaults to entic.net.
 +
 +
 +  POST https://​entic.net/​api/​account/​usage
 +  ​
 +  <​account>​
 +    <​uid>​login</​uid>​
 +    <​domain>​entic.net</​domain>​
 +    <​debug/>​
 +  </​account>​
 +
 +
 +
 +=== Response ===
 +
 +HTTP/1.1 Status response codes with message
 +  400 on validation failures
 +  <​account>​
 +    <​result>​error</​result>​
 +    <​message>​uid:​ too short</​message>​
 +  </​account>​
 +  ​
 +  201 on success, with this response body
 +  <​account>​
 +    <​result>​success</​result>​
 +    <​usage>​
 +      <search max="​200">​150</​search>​
 +      <entries max="​200">​50</​entries>​
 +      <size max="​5242880">​2893832</​size>​
 +    </​usage>​
 +  </​account>  ​
 +  ​
ldapbook_api.txt ยท Last modified: 2010/10/19 21:31 by admin