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:8080/restapi/deals/airfares/list.xml?fromairport=sfo&toairport=lax
http://www.tgels.com:8080/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:8080/restapi/deals/airfares/list.xml
http://www.tgels.com:8080/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:8080/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:8080\/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:8080\/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:8080\/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:8080\/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:8080\/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:8080/restapi/deals/airfares/list.xml?fromairport=sfo&toairport=lax
http://www.tgels.com:8080/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:8080/restapi/deals/airfares/create.xml
http://www.tgels.com:8080/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:8080/restapi/deals/airfares/delete.xml
http://www.tgels.com:8080/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:8080/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