Data Formats
The Address Book Web Service API accepts Request data and outputs Response data in either XML or JSON format.
XML
XML format is self-documenting and easily parsed with XPath or SimpleXML. The following rules define the mapping from entities to XML primitives:
- Each entity is represented as an XML element of the same name, using dashes '-' instead of underscores '_'.
- Composition is represented by element nesting.
- Unstructured data (that is, the property modeled as "data")
is represented using a Text child node; for example, the
phonefield. - Each component of structured data is represented using the
Text value of a nested child element; for example, the
namefield. - Scalar metadata is represented using XML attributes, for
example "work", which you can see in the following example. See
XML Versioning and Validation (DTD) for more details.
Note
Although the examples in this documentation show XML documents indented for readability, the actual output from the Address Book XML API is not indented. No whitespace Text nodes are added between elements; therefore, the output is on one long line.
Example
This example gets the name and phone number of the contact having the specified email:
The Response contains a single Contact with one structured name field and one unstructured phone field. There are two levels of composition and some metadata (Contact ID).
This is an XML representation of the Response:
XML Versioning and Validation
All XML documents returned by the API start with an XML prolog containing both an XML version/encoding declaration, and a Document Type Declaration. The Document Type Declaration (DOCTYPE) points to a versioned external DTD. Although a DTD is referenced, the XML document is standalone. Clients of the API do not need to DTD-validate server responses at run-time.
XML documents that are POSTed to the API must start with an XML prolog that contains at least the XML version and encoding declaration. A Document Type Declaration can be used, and if it is, it must match what the Address Book servers were using when that particular integration was implemented. Independently of whether a DTD is being referenced or not, the XML document must be standalone. Address Book servers will not fetch and parse a remote DTD. This use of DOCTYPE provides an informal versioning mechanism for the XML API. However, even without this mechanism, properly implemented clients should be, by design, forwards compatible, and Address Book servers will be written to be backwards compatible.
JSON Format
The JSON format represents data as
JavaScript literals. The object literal produced by JSON can be
directly evaluated by a JSON parser (such as json_decode
in PHP or the json.org JSON
library).
The following rules define the mapping from entities to JSON primitives (arrays, objects and properties):
- Underscores are used instead of dashes for name properties and for entity types.
- Each entity is represented as an object.
- The type of the entity is represented as the property "type".
- Metadata is represented as object properties.
- Unstructured data is represented as the property "data".
- Structured data is represented using an object with each component represented as a property of that object.
- Composition is represented as a property. There can be two
kinds of composition relationships between parent and child
entities:
- Only a single child is permitted by the schema. In this case, the parent object will have a property referencing the child object directly
- Zero, one, or multiple children are permitted by the schema. In this case the parent object will have a property referencing an array of child objects. This array can also be empty or contain a single element.
It can be known statically if a particular property needs to be accessed as an object, or as an array of objects, which removes type-checking complexity on the receiving side. Although most data is stored in single-element arrays, this representation suggests fields are potentially multi-value. The plurality of a property is the same as the name of the composition relationship between the two entities. If the schema allows multiple children, the name of the property is plural. If the schema allows a single child, the name is singular.
Note
Although the examples throughout this specification show JSON structures indented for readability, the actual output from the Address Book JSON API is not indented.
Example
The search Response containing a single contact with name and phone fields (shown in the XML example above), looks like the following in JSON format: