User Tools

Site Tools


ldapbook_api

CloudFace API

Integrate the 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:

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 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 Entic.net.

Contacts

All contacts created using the 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