This is an attempt at an API over HTTP for the PhillyCarShare reservation
system. It is built to run on Google App Engine, though there should be very
little App Engine-specific code. It should be easily adaptable to a Django
install, or some other Python web framework.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


QUESTIONS
~~~~~~~~~
(I don't have an FAQ yet, but these are questions that I'd ask, at least)

Q: What format is the data?
A: JSON. Not JSON-P for now, so if you want to use it from JavaScript, you're
   going to need a proxy on your server. I might add JSON-P in the future, and
   maybe XML, but I have need for neither right now. If you'd like to add
   JSON-P, it shouldn't take much work. If you'd like an idea of where to start,
   drop me a line.

Q: Can I set up my own instance?
A: Absolutely! The API is written in Python as a WSGI application. It has an
   AppEngine application instance already, so if you want to run it on
   AppEngine, it should take little to no modification. If you want to run it on
   something else, like Django, it will take some modification, though I'm
   working to make sure that it doesn't take too much (still a work in progress
   though!).

Q: Does this only work with PhillyCarShare?
A: I don't know. PhillyCarShare uses software from MetaVera to manage their
   reservations. I do not know the structure of other MetaVera-built reservation
   managers. I am only able to test this against PhillyCarShare, as I only have
   a PCS account. If you want to test against another MetaVera site, feel free.
   If you want me to test it, that's fine too, but I'd need some credentials
   (i.e. userid and password).

Q: Is this legal?
A: In short, yes.  But it's also a bit of an experiment.

Q: Is there documentation?
A: I'm working on it.


~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

API OVERVIEW
~~~~~~~~~~~~

Some things to remember about the API:
  - The only available data format for now is JSON.  So, just remember: 
    [format] = json.
  - Most of the requests will expect a valid session id in a cookie named
    'session'. A session id is returned from the /session.json URL. So, of
    course, you will not need a session cookie for requests to /session.json

/session.[format]
POST
    Create a new session from the given user credentials.  Note: this should be
    done through a secure connection, since credentials are submitted. Also
    note: the API does not store any submitted usernames or passwords. It will
    only pass that information along to PhillyCarShare's system.
    
  - Params:
    user
    password
    
  - Response:
    Response will contain a session identifier in a cookie. This cookie should
    be sent with any subsequent calls to the API.

/locations.[format]
GET
    Retrieve a list of the user's pre-defined locations.
    
/locations/[id]/availability.[format]
GET
    Check for available vehicles near the given location.
  
  - Params:
    start_time (ISO8601 string - defaults to now rounded to next 15 minutes)
    end_time (ISO8601 string - defaults to 3 hours later than start_time)
  
  - Note:
    The [id] in the url may be a saved location profile id, a set of GPS
    coordinates (e.g., '/locations/[long],[lat]/avail...'), or '_default' to use
    the user's default location profile.

/vehicles/[id]/availability.[format]
GET
    Check the availability (and price) of a given vehicle during a certain time
  
  - Params:
    start_time (ISO8601 string)
    end_time (ISO8601 string)

/reservations.[format]
GET
POST

/reservations/[id].[format]
GET
PUT

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

STRUCTURE
~~~~~~~~~
The pcs package is where most of the work happens. It is arranged into four
sub-directories:

 * data: The general data model for the API.  These are simple classes that 
   don'treally do anything aside from hold data.
   
 * wsgi_handlers: This contains modules for input handlers. The only input
   handlers being implemented right now (and probably ever to be implemented)
   are WSGI handlers.
   
 * fetchers: This contains modules for constructing various objects in the data
   model from the information at some source. For example, these modules may
   communicate with the reservation system on PCS's servers. The only sources
   implemented now are screenscraped, as PCS doesn't have a public API that I
   know of (hence this project).
   
 * renderers: This contains modules for representing the API data model. One
   view is JSON data, but there are definitely other possibilities (e.g., XML).


TESTING
~~~~~~~
Most of the code is well tested, and the tests are an important part of the 
package, especially since the only source for now is screenscraping.  The tests
reside in the 'test' directory.  To run the tests, start the appengine
server, and browse to http://localhost:8080/test.  Make sure to sign in as 
administrator.  

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


ADDITIONAL NOTES
~~~~~~~~~~~~~~~~

Background
----------

I'm using this project to overcome the following situations:
- PhillyCarShare does not appear to have a public API for their reservation
  system.
- The full website is a beast to browse on any mobile device.  It's bearable on
  and iPhone, but far from ideal.
- There are little features that would be nice to have that are not available 
  through the main PCS site, that I'd like the option of building.


Testing Guidelines
------------------

Here are my testing guidelines:
- Tests are important.  That's pretty much always true, but especially so for
  this project.  I currently have no API as even a loose contract with PCS, and
  at any time they could choose to change anything about their web interface.
  Since I am dependent on screenscraping said interface, I need to know ASAP 
  when something breaks.  Automated tests are thus a large part of my disaster-
  prevention strategy.  They also make refactoring really easy, which is nice,
  because I'm really indecisive with my design decisions.
  
  I created a few decorators to automatically check the method names and 
  parameter order on my stubs and patches.  The class decorator @Stub allows
  you to specify a class to create a stub of.  If you then attempt to create
  a member method of the stub that does not match the signature of some method
  of the original class, an error will be raised.  The function decorator 
  @patch allows you to override a method on a class (or a Stub class), and 
  automatically verifies that the signature of the patch matches a method on 
  the actual class.
  
- I will not put my PCS userid/password anywhere in this project, and no one
  else should either.  This type of thing should go in the private_info file in 
  the test directory.  Copy private_info.py.template to private_info.py, and 
  enter your credentials there.  Changes to this file will not be checked in.


Reservation Identifiers
-----------------------

In the PCS system, every reservation made has a unique identifier. However, the
ID that the user sees is the confirmation ID, not the reservation ID (this is
still called the reservation ID on things like the reservations list and the gas
remibursement request form though). There is a way to get information on a
reservation with the reservation ID, but it doesn't seem that there is any way
using the confirmation ID, aside from browsing through all of the reservations
listings.

The best way to get information on a single reservation is with the reservation
ID. This is only available (to my knowledge) for current and upcoming
reservations. If there is a guarantee that confirmation IDs are monotonic with
respect to the reservation date, then I can do a binary search through the
reservation lists for a specific reservation.  However, I do not yet have a way
to recover the actual reservation ID for a past reservation given just the 
confirmation ID.