Technical Resources

This section provides some links to external technical resources related to SAPI.

HTTP 1.1 (Hypertext Transfer Protocol)

The protocol used for sending and receiving API messages is HTTP Version 1.1. Basic knowledge of this protocol is recommended. However, depending on the programming language and tools being used, an in-depth understanding of HTTP may not be required.

External resources:

HTTP 1.1 Specification
HTTP Status Codes
W3C Protocols Page (more information and specification updates)

URLs (Uniform Resource Locators)

URLs are used (in conjunction with HTTP) to specify the location of the SAPI server, the type of search and the search parameters. A thorough understanding of URLs is recommended, specifically the encoding of prohibited characters.

External resources:

URL Specification
URL Encoding
W3C Addressing Page (more information and specification updates)

JSON (JavaScript Object Notation)

JSON is a lightweight data-interchange format used in all SAPI response messages. The actual listings are returned in JSON format, as well as status codes and messages. Familiarity with JSON is essential. However, depending on the programming language and tools being used, an in-depth understanding may not be required.

External resources:

JSON website (specification, other resources and libraries)

Web Browsers and JSON

All you need to try out the API is a good web browser. The API is based on HTTP GET requests, and returns human-readable JSON responses. However, not all browsers handle the JSON responses very well.

Some browsers will happily display the JSON text, while others will prompt you to download the response as a file. If your browser does prompt you to download a file, simply open it up with a text editor such as Notepad for viewing. Some older browsers may simply refuse to render or download the response at all.

We recommend you use one of the following browsers for testing out the API:

Firefox 3.6 (or above) with JSONView plug-in (see below)
Chrome 8 (or above)
Safari 5 (or above)

Note: The fact that certain browsers cannot handle JSON will have no effect on what browsers can be used to view your website. JSON is only used as the protocol between SAPI and your application. What happens beyond that is completely within your control.

Viewing JSON as text can sometimes be hard to read. To make the JSON even more readable you can use a JSON formatter plug-in. There is plug-in called JSONView that formats JSON response messages using colour and indenting. Unfortunately it is currently only supported in Mozilla Firefox.

HTTP Client Library

In order to send API requests, you will need to be able to communicate with the API endpoints using HTTP. The library you use depends on the type of website or application, and the programming language being used.

Some recommendations:

For Java, see the HttpURLConnection class or the Apache HttpClient library.
For PHP, see the HttpRequest class.
For JavaScript, see the XMLHttpRequest object.
For Ruby, see the Net::HTTP object.

For other programming languages please, consult the language documentation.

See also: Code Examples

JSON Parser

The response messages returned by the API are encoded in JSON. Depending on the programming language or framework you are using, you will probably need a JSON parser. An extensive list of JSON libraries can be found on the JSON website.

Some recommendations: