The address book service will return an XML or JSON formatted list of contacts for a user in response to a GET request that provides correct authentication credentials via HTTP Basic Authentication. The service supports filtering, pagination and sorting according to the portable contacts specification and all queries should be formatted accordingly. A response containing one entry in XML formatting has the structure seen below. Each contact entry will contain one or two email addresses. The first email will always have the form "<username>@<faspex_host>" and will be marked as the primary email of the contact. In the event that the authenticating user is allowed to send to external emails, a secondary email address external to faspex will be included with some contacts, which is the email address associated with that user's account in Faspex (the email address at which the user normally receives notifications).
The username portion of each email address is url-encoded (or percent encoded), so that any email address returned by the service contains exactly one '@' character, although its username portion may contain additional, encoded '@' signs (to illustrate this point, for a user with username 'email@example.com' the address book will return a listing containing the email address 'firstname.lastname@example.org'). By default, each contact includes a 'tags' field that will include one of the tags; 'workgroups', 'users' or 'external-users'. These tags correspond to the type of contact in faspex. Contacts' IDs are guaranteed to be unique strings, but no additional specifications are available for IDs. In the faspex 1.7+ implementations, IDs will have the following structure:
- Normal Users - IDs corresponding to the their ID in the system.
- Workgroup Users - IDs comprised of their IDs in the system prefixed by the string 'wg'.
- External Users - IDs consisting of the string 'ex' followed by a number
- Location: /address-book
- Supported Formats: XML, JSON
- faspex Support: 2.X +
XML Entry Response Example
Several available queries and the content of their response is presented in the table below. The path is relative to the address-book service URL.
|Path + Query||Content of Response|
|/@me/@self||list containing a single entry describing the authenticated user|
|/@me/@all||list containing entries for each contact in the authenticated user's address book|
|/@me/@all/6||list containing a single entry describing the contact with ID equal to 6 (or an error if no such contact exists in the authenticated user's address book)|
|/@me/@all?sortBy=displayName&sortOrder=ascending||list containing a single entry for each contact in the authenticated user's address book, sorted by their displayName in ascending order|
|/@me/@all?count=10||list containing a single entry for the first 10 contacts found in the given ordering|
|/@me/@all?count=10&startIndex=20||list containing a single entry for each of the 10 contacts at indices 20-29 according to the given ordering|
|/@me/@all?filterBy=displayName&filterOp=startswith&filterValue=sam||list containing a single entry for each contact in the authenticated user's address book whose displayName starts with 'sam'|
An example cURL command is seen below, this queries the service at the URL https://10.0.160.5/aspera/faspex/address-book/@me/@self?format=xml. In the command below admin:aspera is the credentials for the user admin. The default response format will be JSON, if you wanted to change to XML the format parameter would need to be set to XML.
curl -k --basic -u admin:aspera "https://10.0.160.5/aspera/faspex/address-book/@me/@self?format=xml"
An example of the same cURL command, but in Ruby programming is seen below.
The success or failure of a request will be determined by the HTTP response code. Although faspex may return additional information in the body of a response, this data will be ignored by clients and should not be relied upon. The following table lists the response codes supported by faspex, a description of the situations they cover, and an example query that should trigger that response code.
|Response Code||Description||Example Query|
|200 (OK)||Query succeeded||/@me/@all|
|400 (Bad Request)||Invalid query (according to the PC specification)||/@invalid_path|
|401 (Unauthorized)||Authentication failed||/@me/@all [using invalid credentials]|
|404 (Not Found)||Invalid contact id||/@me/@all/2718_invalid_id|
|500 (Internal Server Error)||The server encountered an internal error||N/A|