Airfares   Hotels   Deals   Products    IM   Login    
REST APIs 1.0 alpha
REST Web Service

A REST WebService uses a state and identifier to access a resource and change states. The identifier is usually a noun. A state is a snapshot of something. A state can lead to other states which provide snapshot of things. The snapshot can be filtered by applying criteria in the form of parameters. Similarly an entity can be created, deleted or updated. The entity values are supplied as parameters. A REST WebService uses the http protocol. The http methods used are:
HTTPOperation
POSTCreate
GETRead
PUTUpdate
DELETEDelete

tgels REST API

tgels REST apis are very easy to use, and can be accessed with a http client like a browser or an application. It is of the form http://www.tgels.com/restapi/[id].format. [id] is an identifier and is of the form /deals/airfares/list. /deals/airfares/list identifier returns a list of all deals available. An id of the form /deals/airfares/create creates a new deal, while an id of the form /deals/airfares/delete deletes an existing deal. Accessing an identifier is an operation. An operation can be a HTTP get/put/delete or post. A get retrieves something, while a post creates something, a post/delete deletes something while a post/put updates something. Parameters can be supplied to these operation to filter the response or create a deal or to identify a deal. For eg. /deals/airfares/list returns the first page of all deals. Parameters can be used to filter the deals. For eg. fromaiport='sfo', and toairport='lax' can be used to apply a filter to return deals from/to sfo/lax airports.

You can access the below URLs with browser or use the example TgelsRestApi application to try it out:

http://www.tgels.com:80/restapi/deals/airfares/list.xml?fromairport=sfo&toairport=lax
http://www.tgels.com:80/restapi/deals/airfares/list.json?fromairport=sfo&toairport=lax

It will prompt you for a login/password, please enter your tgels login id/passwd.

Note:
The apis can only be accessed across port 8080 for now. Port 8080 accesses a test database and not the live database, allowing you to become familiar with the api. The live access should become available shortly. All accesses need your tgels.com id.

Methods

List Method

http://www.tgels.com:80/restapi/deals/airfares/list.xml
http://www.tgels.com:80/restapi/deals/airfares/list.json

http operation:

GET

Formats:

xml, json

Parameters:


A key-value pair of the following:

	key: fromairport

		value: an airport code

		type: String

		required: optional

	key: toairport

		value: an airport code

		type: String

		required: optional

	key: site

		value: a site name of form, Spirit.com, Southwest.com, Delta.com, USAir.com, AA.com, Continental.com, Airtran.com, etc.

		type: String

		required: optional

	key: price

		value: > 0

		type: float

		required: optional

	key: page

		value: >= 0

		type: int

		required: optional		


Returns:

Returns a list of deals in json or xml or html format as requested. If no parameters are supplied, then the first page all available deals is returned. The number of pages, page size, page number is returned so that you can iterate through the deals. The response is in XML or JSON or html format depending on how you suffix the identifer.

Response in xml format:


<restapi>

  <name>tgels_restapi</name>

  <version>1.0</version>

  <request>

    <name>/deals/airfares/list.xml</name>

    <parameters>fromairport=sfo&toairport=lax</parameters>

    <userid>nn1</userid>

  </request>

  <response>

    <data class="deals">

      <pages>1</pages>

      <pagesize>15</pagesize>

      <page>0</page>

      <rows>

        <deal>

          <id>142678</id>

          <found>2009-3-19</found>

          <fromairport>sfo</fromairport>

          <toairport>lax</toairport>

          <fromcity>San Francisco</fromcity>

          <tocity>Los Angeles</tocity>

          <url>http://www.tgels.com:80/restapi/deals/airfares/list.jsp?from=sfo&to=lax&id=142678&price=0.0</url>

          <price>0.0</price>

          <travelperiod>null</travelperiod>

          <currency>null</currency>

          <advancedays>0</advancedays>

          <multiple>0</multiple>

          <username>null</username>

          <userid>null</userid>

          <oneway>true</oneway>

          <business>false</business>

          <first>false</first>

          <ambiguous>false</ambiguous>

        </deal>

      </rows>

    </data>

    <date>3/20/2009</date>

    <status class="ok">

      <msg>Ok</msg>

    </status>

  </response>

</restapi>


The <request> element contains sub elements <name> which names the request, <parameters> used to filter the response, <userid> making the request. The <response> element contains elements <data> which has an attribute class which describes the type of data being returned. If the class type is Deals, then the response is rows of Deal. A Deal is a sale fare containing elements <id><found><fromairport><toairport>, etc.

Response in json format:


{"restapi":{"name":"tgels_restapi","version":1,"request":{"name":"\/deals\/airfares\/list.json","parameters":"fromairport=sfo&toairport=lax","userid":"nn1"},"response":{"data":{"@class":"deals","pages":1,"pagesize":15,"page":0,"rows":{"deal":[{"id":142678,"found":"2009-3-19","fromairport":"sfo","toairport":"lax","fromcity":"San Francisco","tocity":"Los Angeles","url":"http:\/\/www.tgels.com:80\/restapi\/deals\/airfares\/list.jsp?from=sfo&to=lax&id=142678&price=0.0","price":0,"travelperiod":"null","currency":"null","advancedays":0,"multiple":0,"username":"null","userid":"null","oneway":true,"business":false,"first":false,"ambiguous":false},{"id":142683,"found":"2009-3-19","fromairport":"sfo","toairport":"lax","fromcity":"San Francisco","tocity":"Los Angeles","url":"http:\/\/www.tgels.com:80\/restapi\/deals\/airfares\/list.jsp?from=sfo&to=lax&id=142683&price=1.0","price":1,"travelperiod":"null","currency":"null","advancedays":0,"multiple":0,"username":"null","userid":"nn1","oneway":true,"business":true,"first":true,"ambiguous":false},{"id":140318,"found":"2009-3-10","fromairport":"lax","toairport":"sfo","fromcity":"Los Angeles","tocity":"San Francisco","url":"http:\/\/www.tgels.com:80\/restapi\/deals\/airfares\/list.jsp?from=lax&to=sfo&id=140318&price=47.0","price":47,"travelperiod":"null","currency":"","advancedays":21,"multiple":0,"username":"null","oneway":true,"business":false,"first":false,"ambiguous":false},{"id":134162,"found":"2009-3-4","fromairport":"sfo","toairport":"lax","fromcity":"San Francisco","tocity":"Los Angeles","url":"http:\/\/www.tgels.com:80\/restapi\/deals\/airfares\/list.jsp?from=sfo&to=lax&id=134162&price=49.0","price":49,"travelperiod":"null","currency":"","advancedays":0,"multiple":0,"username":"null","oneway":true,"business":false,"first":false,"ambiguous":false},{"id":140375,"found":"2009-3-10","fromairport":"lax","toairport":"sfo","fromcity":"Los Angeles","tocity":"San Francisco","url":"http:\/\/www.tgels.com:80\/restapi\/deals\/airfares\/list.jsp?from=lax&to=sfo&id=140375&price=109.0","price":109,"travelperiod":"null","currency":"","advancedays":21,"multiple":0,"username":"null","oneway":true,"business":false,"first":false,"ambiguous":false}]}},"date":"3\/20\/2009","status":{"@class":"ok","msg":"ok"}}}} 


Example:

You can give this a try using a browser or the example TgelsRestApi application:

With a browser type/click on below URL:
http://www.tgels.com:80/restapi/deals/airfares/list.xml?fromairport=sfo&toairport=lax
http://www.tgels.com:80/restapi/deals/airfares/list.json?fromairport=sfo&toairport=lax

It will prompt you for a login/password, please enter your tgels login id/passwd.

You can also install/run thelibrary code to try this out.


Create Method

http://www.tgels.com:80/restapi/deals/airfares/create.xml
http://www.tgels.com:80/restapi/deals/airfares/create.json


http operation:

POST

Formats:

xml, json

Parameters:

A key-value pair of the following:

	key: fromairport

		value: from airport codes like sfo, lax, etc.

		type: String

		required: always            

	key: toairport

		value: to airport codes like jfk, iad, etc.

		type: String

		required: always       

	key: fromcity

		value: from city like San Francisco, etc.

		type: String

		required: always

	key: tocity

		value: to city like New York, etc.

		type: String

		required: always

	key: price

		value: > 0.0

		type: float

		required: always    

	key: site

		value: SpiritAir.com, Southwest.com, Delta.com, Airtran.com, AA.com, ...

		type: String

		required: always  

	key: url

		value: a url of form http://... to transfer the user

		type: String

		required: always                                                   

		

Optional paramters:

	key: expirebegin

		value: a date value of format "yyyy/mm/dd". Expire begin date.

		type: String

		required: optional

	key: expireend

		value: a date value of format "yyyy/mm/dd". Expire end date.

		type: String

		required: optional

	key: currency

		value: $, USD, CAD, EUR, etc. Default $ if no value.

		type: String

		required: optional 

	key: roundtrip

		value: 1 or 0. Default 0, oneway.

		type: int

		required: optional        

	key: economy

		value: true/false. Default true.

		type: boolean

		required: optional  

	key: business

		value: true/false. Default false.

		type: boolean

		required: optional              

	key: first

		value: true/false. Default false.

		type: boolean

		required: optional

	key: travelperiod

		value: travel dates, a string like "3/10, 3/20 or similar"

		type: String

		required: optional                                        

	key: travelbegin

		value: a date value for when travel should begin, of format yyyy/mm/dd.

		type: String

		required: optional                            

	key: travelend

		value: a date value for when travel should end, of format yyyy/mm/dd.

		type: String

		required: optional                            

	key: comments

		value: a desc of the deal, etc.

		type: String

		required: optional              

Request needs to be application/x-www-form-urlencoded which is the default for http post operation.  Content type must be encoded as follows:

1.Control names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').

2.The control names/values are listed in the order they appear in the document. The name is separated from the value by `=' and name/value pairs are separated from each other by `&'.

You can get more information about application/x-www-form-urlencoded here.

Returns:

A response in xml or json as requested. Response contains the Deal created with its id or (null or deal is 0). An Error status is returned in case of any errors. msg should contain the error msgs.

Delete Method

http://www.tgels.com:80/restapi/deals/airfares/delete.xml
http://www.tgels.com:80/restapi/deals/airfares/delete.json

http operation:

POST/DELETE

Formats:

xml, json

Parameters:

A key-value pair of the following:

	key: id

	value: id of deal to be delete

	type: int

	required: always

Example:

http://www.tgels.com:80/restapi/deals/airfares/delete.xml?id=12345

Returns:

A response in xml or json as requested. Response contains status which should be ok or error


Authentication

All API methods require authentication. Only HTTP Basic Authentication is supported for now.
HTTP Status Codes:
The REST API returns the following HTTP status codes :

200 OK: everything went awesome. 

400 Bad Request

401 Not Authorized


Error Messages

When the REST API returns error messages, the status class will be Errror, and contains an array of Strings. The Strings are different error msgs returned by different sections of the operation.
restapi={"response":{"status":{"msgs":{"String":["fromcity/tocity = seem to be the same"]},"@class":"Error"},"date":"2009-2-15"},"request":{"name":"/deals/airfares/create.json","userid":"demo","date":"2009-2-15"},"name":"tgels_restapi","version":1}


REST API More Info

1.http://en.wikipedia.org/wiki/Representational_State_Transfer
2.http://www.infoq.com/articles/rest-introduction
3.http://www.xml.com/pub/a/2005/04/06/restful.html
4.http://apiwiki.twitter.com/REST+API+Documentation
5.http://wiki.developer.mindtouch.com/REST/REST_for_the_Rest_of_Us

Download Library/Example Code

Java