WhereYouAre

Design

(round2)

   REST summary
   ------------
   every resource has to be discoverable via links
       basically a developer can learn the API with a browser
       also, with links, you can mingle resources from any REST api
   verbs
       GET - retrieve a specific resource
       DELETE - delete a specific resource
       PUT - update a specific resource
       POST - create a new resource and return the ID - neither safe nor idempotent
       you can repeat calls to GET/DELETE/PUT all day long if they fail
   complex functions (eg query and result) as resources
       create a query resource with a TTL
       add to it
       execute it (and auto-release?)
       release it (or let this happen automatically with server-side TTL cleanup)

   how do we handle huge lists?  like this?
       wya/users
           returns the first 10 users with a link to next 10
       wya/users/range/11-20
           a link to users 11-20

   {resource}/edit should return an edit form (cool) - I think recess already does this?

   authentication - use SSL with HTTP Basic Authentication, or SHA1 signature (ala Amazon S3)

   wya API requirements
   ------------------------------------------
   https put "my friends subscription" (on startup)
   https put "my location" every 15 seconds (may be "stealthmode") \ 
   https get "my friends' locations" with ages (may be "stealthed")/ combine?
   https post "my new friend" with phone number and stealthstatus
   https put "my friend" with phone number and updated stealthstatus
   https delete "my friend" with phone number
   https put "ping this friend" with phone number
   https put "logoff"

   NOT needed...
   -------------
   put "i am running the app" (implied by [put my location])
   put "my friend" (the server only tracks phone number, no editing available)
   any meetup or ignore state
       ignore is done by deleting friend
       meetup is done by client requesting pings

   wya server requirements
   -------------------
   track friend {phone,location,refcount} array
   track activeuser {phone,stealthmode,friendarray} array
   collect friend locations "by any means necessary"
   reply to API requests
       only report locations if not stealthed
       only report locations if under a day old?
   use TTL of 6 heartbeats, kill activeuser after that

   wya client requirements
   -------------------
   maintain complete friends list (even ignored) with prioritization
   ping server with location every 15 seconds
   adjust tracking to include "top n" friends
   "ignore all" mode (similar to "logoff server")

(round1)

   all f's of all users running app need constant location ping
       f's must be shared with phone# as key
       server must track users' flist
       server must constantly work on getting f updates

   user starts up app
       user logs in to server and sends friendlist
       server adds user to userlist, merges friendlist into totalfriendlist (w/refcount?)
       server should do its best to get all friends' locations
           ** this is a separate task from communicating with user **
       user pings server with location, gets f updates
           ping every 15 seconds?
           only send updates if they have not been received by user?  (how to get best performance?)
       user shuts down app (or times out)
       user is logged out of server

   server f location collector
       use external services to poll for location for all f that are not running app	
           ping every 15 seconds?
           users that are running app are all sending locations, no need to collect them

       include occasional push check:
           if f owns app
               if f is not running app
                   if f is in meetup
                       push request to f1

   <iph>			<tdm_rest>		<tdm_pusher>		<apl>			<loc_server>
   -----			-----			-----			-----			-----
   

REST Examples

1. The best example I have to follow is the Twitter API. It *obviously* scales. It uses Basic Authentication, which sucks (everything is plaintext, holy shit). BETTER force it to use SSL.
2. The other excellent example is the Amazon S3 API. Authentication is brilliant - it uses a SHA1 signature of the request, which MUST include a timestamp within the last 15 minutes. There is a set of rules for turning the request URL into the request string that is signed.

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( YourSecretAccessKeyID, StringToSign ) ) );