Home > Nestoria API - Methods - Echo

Let's start with a very simple request. You ask "Are you there?" and the service responds "Yes".

The request is a HTTP GET call to a URL. The response is a data structure either in JSON (default) or XML. The request is repeated in the response (for debugging).

The request sent in this example is as follows:

	  
http://api.nestoria.co.uk/api
  ? action   = echo
  & encoding = json
  & foo      = bar

API calls are made using HTTP GET. The results of the API calls are returned in the body of the HTTP response either as XML or JSON. Requests should be sent to the appropriate server for the country for which listings data is required for.

The example request above would result in the following response (encoded using JSON, formatting added for display purposes):

    {
      "request" : {
        "action" : "echo",
        "country" : "uk",
        "encoding" : "json",
        "foo" : "bar",
        "language" : "en",
      },
      "response" : {
        "action" : "echo",
        "country" : "uk",
        "created_http" : "Thu, 06 Jul 2006 10:59:26 GMT",
        "created_unix" : 1152183566,
        "encoding" : "json",
        "foo" : "bar",
        "language" : "en",
        "status_code" : 200,
        "status_text" : "OK",
        "version" : 1.18
      }
    }

The result is split into two parts - the request and the response. The request is a copy of the request that was sent after all the defaults have been filled in and any bad values stripped out. This is the actual request that was used to create the response.

The response part contains the generated data. The "echo" action simply echoes back all of the request parameters, making it useful for testing. Several fields are added to the response which are always present:

status_code The HTTP status code
status_text The code as text
created_http The time that the results were created, in HTTP format
created_unix The same but as a unix timestamp (seconds since epoch, January 1st 1970)

The request, the status codes and the time-stamps are in the results so that it is easier for you to just save the content of the HTTP response to a cache and still have all the information you might need.

Common Arguments

These arguments apply to all API calls:

action The name of the API methods, e.g. 'echo'
version The API version - allows for backward compatibility. Optional
encoding How the results will be encoded, 'xml' or 'json'
pretty Whether the results will be formatted for more readability
callback Name of function to wrap the JSON in