| 
View
 

API structure

Page history last edited by xuan wang 12 years, 9 months ago

Please NOTE that this documentation will not be updated anymore. Please see our new Developer Documentation Site for the latest updates! The content of this page can be found here.

All calls are RESTful so they adhere to the REST architecture. Currently one HTTP GET call has been defined for fetching resources:

The requests conform to HTTP/1.1. The request parameters are normalized as described in the next paragraph.

 

Currently (updated on 14th Dec 2011), the IP address range of the layar server is:

 

  • 79.125.0.0/17 (79.125.0.0 - 79.125.127.255)
  • 46.51.128.0/18 (46.51.128.0 - 46.51.191.255)
  • 46.51.192.0/20 (46.51.192.0 - 46.51.207.255)
  • 46.137.0.0/17 (46.137.0.0 - 46.137.127.255)
  • 46.137.128.0/18 (46.137.128.0 - 46.137.191.255)
  • 176.34.128.0/17 (176.34.128.0 - 176.34.255.255)
  • 176.34.64.0/18 (176.34.64.0 – 176.34.127.255) NEW

 

This IP range will be updated from now and then.

 

Normalized Request Parameters

All requests will be made using normalized request parameters conforming to the following rules:
  1. Gather the GET query parameters
  2. Parameters are sorted by name, using lexicographical byte value ordering. If two or more parameters share the same name, they are sorted by their value.
  3. Concatenate the parameters in order and delimit as follows:
    1. By name and value with an '=' character delimiter (ASCII code 61)
    2. For parameters containing more than one value, concatenate the values with a '+' character delimiter
    3. By pairs with an '&' character delimiter (ASCII code 38)
  4. If the parameters contain UTF-8 encoded strings, these must be replaced by their corresponding %HH bytes values, see here
  5. URL escape the parameter string.

 

Signing of Requests according to OAuth

Developers can choose to receive signed requests. The signing will conform to OAuth signing requests and the signing parameters can be set for each layer using the Layar Publishing Website. Only HMAC-SHA1 signature method is supported. The Signature Base String is generated using:
  1. The HTTP method: GET
  2. The URL for the request: e.g. http://layarapi.example.net/mylayer/getpoi
  3. The normalized request parameters, including the oauth request parameters, excluding oauth_signature. The oauth request parameters used by the Layar Developer API are: oauth_consumer_key, oauth_signature_method, oauth_timestamp, oauth_nonce, oauth_body_hash and oauth_version.
 
Add example...

 

Response format

The API currently accepts only JSON response format. Make sure your HTTP response headers declare the correct content type: application/json or text/javascript. Also make sure you encode your response in UTF-8 and add charset=utf-8 to your content type header:

     Content-type text/javascript; charset=utf-8 

JSON (JavaScript Object Notation) is a machine-readable data exchange format using conventions derived from the C family of programming languages.

JSON is built on two universal data structures:

  1. A collection of name/value pairs represented as a user-defined object.
  2. An ordered list of values represented by an array.

JSON data separators are identical to those used by JavaScript engines to represent data structures such as strings and arrays. This provides for easier data access than what would be achieved with XML.

JSON is less verbose than XML and lacks certain properties that are available in the latter. For example, namespaces allowing identical pieces of information to be mixed in different contexts in XML are not available in JSON.

Converting from XML to JSON can present challenges when distinguishing between the actual value of attributes and text between tags, because JSON assignments are created with colons.

 

Some general conventions

Date formats: All timestamps are integers, in number of milliseconds since 1/1/1970 UTC. They are currently only used in order to compare values, the absolute value does not matter.

 

Color formats: All colors are integers (base-10), based on RGB: 0xrrggbb where rr is 2-byte hexadecimal code for red (0xFF is maximum), gg is 2-byte code for green and bb is 2-byte code for blue. So a pure yellow color would be 0xFFFF00 which translates to an integer of 16776960. 

 

String formats: All strings are UTF-8 encoded. For the JSON responses, this is part of the JSON specification. For the requests, strings should also be UTF-8 encoded: Each byte or character that is not an ASCII letter or digit should be converted to %HH where HH is the hexadecimal value of the byte. See here for more information on URL-encoding international strings. 

Comments (0)

You don't have permission to comment on this page.