Internationalization
Character Encoding
For internationalization, UTF-8 is strongly recommended for both input and output.
- All strings internally are unicode strings stored in the UTF-8 representation.
- XML output is in UTF-8.
- XML input can be UTF-8 and some other character encodings. The encoding used must be specified in the XML prolog. It is not guaranteed that encodings other than UTF-8 will be supported by the API, and if currently supported, they may not be supported in future releases.
- JSON output uses JavaScript string literal escaping (in the \uXXXX format); JSON output is therefore ASCII (7-bit clean).
- JSON input must use string literal escaping, ASCII (7-bit clean).
- URL parameters, such as search strings, must use UTF-8 character encoding. When building the request URL, encode characters from parameters into bytes using UTF-8 encoding. Afterwards this series of bytes is URL-encoded.
- When building the request URL, do not URL-encode the string represented using a different character encoding than UTF-8.
Examples
These example uses the octal C backslash notation for denoting a byte with the MSB set. The backslash character does not appear literally in the XML document.
XML
The following example submits an XML document using a non-UTF-8 character encoding (ISO-8859-1) and expects Address Book servers to transcode. However, this practice is not recommended:
The same document using UTF-8 (recommended practice):
JSON
This example performs the same operation as the preceding
XML example but in JSON. Note the string literal escaping. This
escaping is performed automatically if you use json_encode in PHP which is UTF-8.
URL Encoding
To demonstrate how strings should be represented in UTF-8 for URL encoding, this example searches for the Gerhard Schröder in the Address Book:
Error Messages
All error responses generated by the Address Book XML/JSON API
contain in the component user-message an error message
string ready to be shown to the end-user. This message is localized
using the language of the account that is being accessed, as long as
the language of the account is known to Address Book servers at that
time. If the language of the account is not known, the user-message
will be in English. See the Error Reporting section for more information about the structure of
the error response.