Introduction

The Homestay Network API is implemented as XML over HTTP. All requests are made to RESTful URIs and all responses are in XML. Be sure to set the "Content-Type" header in your requests to "application/xml", which will identify the format of the data being sent. Also, you must set the "Accept" header to "application/xml", so that Homestay Network will send you XML in reply, instead of HTML. Example with Curl:

curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' -d '<request>...</request>' http://api.homestaynetwork.org/countries

Authentication

Authentication is required for all requests for private data, including Hosts/Students/Products etc.

Authentication must be performed in the following manner:

1) Basic HTTP authentication request

An HTTP Request is made to http://api.homestaynetwork.org/authorise including Basic HTTP Authentication (API Key/password). Here's an example using Curl:

curl -u abc1234xyz5678:passW0rd -0 http://api.homestaynetwork.org/authorise

2) Authorisation response

Successful authorisation will return an XML document with the following content:

<response>
	<status>200</status>
	<message>Your authorisation has been granted</message>
	<token>1234abcd5678wxyz</token>
</response>

Authorisation failure will return a similar document with status 403, excluding the token.

3) Subsequent requests

Upon successful authorisation, a unique token is generated with a 10 minute expiry period. All subsequent requests for private data must be accompanied with this token parameter. Here's an example using Curl:

curl -H 'Accept: application/xml' http://api.homestaynetwork.org/hosts/?token=1234abcd5678wxyz

Each request that is received will extend the token's expiry period by another 10 minutes.

Response statuses

Response statuses will adhere to the HTTP standard status response codes.

200: HTTP_OK
201: HTTP_CREATED
Returned when a new record has been created
403: HTTP_FORBIDDEN
Authorisation failed (for API KEY/Password)

Homestay Network API