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.
Normalized request parameters
All requests will be made using normalized request parameters conforming to the following rules:
- Gather the GET query parameters.
- 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.
- Concatenate the parameters in order and delimit as follows:
- By name and value with an '=' character delimiter (ASCII code 61)
- For parameters containing more than one value, concatenate the values with a '+' character delimiter
- By pairs with an '&' character delimiter (ASCII code 38)
- If the parameters contain UTF-8 encoded strings, these must be replaced by their corresponding %HH bytes values, see here.
- 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:
- The HTTP method: GET
- The URL for the request: e.g. http://layarapi.example.net/mylayer/getpoi
- 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.
GetPOIs Response format
- A collection of name/value pairs represented as a user-defined object.
- An ordered list of values represented by an array.
Some general conventions
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.
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.
All strings are UTF-8 encoded.
- 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.
- For the JSON responses, this is part of the JSON specification. Your JSON response can contain UTF-8 encoded strings. However, HTML formatting is not supported. Please use UTF-8 for special characters.
- For url strings (starts with http:// or https://) in JSON response, please make sure that they are valid according to RFC1738. Basically, the following rules are applied:
- spaces should be encoded using %20 (not +, since it is not accepted by layar currently).
- special characters in other languages should be encoded, such as Chinese characters.
- reserved characters like ";" , "/" , "?" , ":" , "@" , "=" and "&" should be encoded when it is used in an octet.
- only alphanumerics, the special characters "$-_.+!*'(),", and reserved characters used for their reserved purposes may be used unencoded within a URL.
- http://custom.layar.nl/layar image.jpeg should be http://custom.layar.nl/layar%20image.jpeg ->space should be encoded as %20
- http://custom.layar.nl/focus图 像.png should be http://custom.layar.nl/focus%E5%9B%BE%E5%83%8F.png -->special characters in other languages should be encoded.
IP address range of Layar Server
Currently (updated on 20th March 2012), the IP address range of the layar server is:
- 188.8.131.52/17 (184.108.40.206 - 220.127.116.11)
- 18.104.22.168/18 (22.214.171.124 - 126.96.36.199)
- 188.8.131.52/20 (184.108.40.206 - 220.127.116.11)
- 18.104.22.168/17 (22.214.171.124 - 126.96.36.199)
- 188.8.131.52/18 (184.108.40.206 - 220.127.116.11)
- 18.104.22.168/17 (22.214.171.124 - 126.96.36.199)
- 188.8.131.52/18 (184.108.40.206 – 220.127.116.11)
- 18.104.22.168/16 (22.214.171.124 – 126.96.36.199)
NOTE: This IP range will be updated from now and then. If you experience any issue, please contact us at http://devsupport.layar.com.