useless-wait-list 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: acf3ad7bf2fd27f864f7ec9b3ab551c878bed013
-  data.tar.gz: e99e8e1c64ba5b4f2ae0988966657f3c6abb26aa
+  metadata.gz: 53d5029e8f1334b1d10735161db301e1d98ed3e0
+  data.tar.gz: a84e1cec60ccd925e0a9dba00beffeee9a4c4b2d
 SHA512:
-  metadata.gz: 2787c9e01b6bb479429a8d379a07efff3bbb79d6cbafae815a51df274bfae50ba82974693d2f6e7a8cc7b07ffdf643099c4933f09b10a68046fa0dae02a6164f
-  data.tar.gz: a39141772f80efc93a58bec013e7dc004470a2adba18a6252ad79eaec4a05871922bee92a4b5c4b3d1c4c697f9142e919c6d0c72f8a69bde7124ab7bb368657e
+  metadata.gz: edc115913a5955709667a9e645f32d3e49f34f9202c4626f55d1ab185ba468f28a85c2891765a282c81239e5b2aa8a74023f9e3706545be0b21a0caa807c6f61
+  data.tar.gz: d83b44b4dc30370efbe915ffaea2b88e4b6593010a5f0c5876b12eb29b5d06762eb8a078d4f515fba3bf1467b6f5604970454ddee036e6afc57f8c151a404828

data/lib/useless/wait_list.rb

@@ -14,55 +14,111 @@ module Useless
       implementation 'Pending', 'Kevin Hyland'
 
       description <<-DESC
-        It is becoming increasingly common for restaurants, especially popular
-        ones, to not accept reservations. Instead, they choose to maintain a
-        first-come, first-served wait list.
-
-        Algorithmically, this makes a lot of sense. The wait list can be
-        modeled as a set of queues, one per available table size. The
-        reservation, however, requires some scheduling algorithm. Queues, in
-        general, are easier than scheduling.
-
-        This is reflected in the real world. Reservations force the restaurant
-        to commit to an explicit time that the table will be available, which
-        is difficult to do accurately. The simplicity of the wait list, though,
-        allows both patron and proprietor to better understand the real time
-        that a table will be available.
-
-        And although patrons appreciate more realistic expectations, the
-        overall quality of their experience is decreased when compared to
-        reservations. If you live in a neighborhood where most restaurants do
-        not take reservations, and you're looking for a restaurant, it's not
-        uncommon to walk to a bunch of places and then ultimately walk back to
-        the one that had the shortest wait list. The best way to get a good
-        spot on a particularly popular wait list is to show up in the early
-        afternoon. But it doesn't have to be that way!
-
-        The goal of the **Wait List API** is to make the process of getting and
-        being on a wait list _better_ than that of making a reservation. The
-        main idea, of course, is that if a wait list is represented as an
-        intuitive JSON API, then there a few ways that the patron experience
-        can be signifcantly improved:
-
-        1.  A patron could browse all the wait lists of all the restaurants in
-            his area, ordering them by the estimated time that a table will
-            be available for his party size. He could then put himself on the
-            wait list that works best.
-
-        2.  Once on a wait list, the patron could have complete visibility into
-            his position in line. He wouldn't have to arrive at the restaurant
-            until exactly when his table was ready.
-
-        3.  For popular restaurants, there could be a flash sale experience
-            when the wait list opens for that night's dinner. A patron could
-            contend for his position on a wait list from his office computer or
-            on his phone.
-
-        Restaurants would benefit as well. First of all, the task of managing
-        the wait list is simplified since the patrons are doing it on their
-        own. Secondly, they would have access to all the data captured by the
-        API.
+        The **Wait List API** exposes a service that improves the wait list
+        experience for both restaurants and patrons. It was initially motivated
+        by a desire, as patrons, to browse and add ourselves to wait lists. It
+        also improves the process of managing wait lists for restaurants.
+
+        ### Restaurant
+
+        The top-level resource is the **restaurant**, which consists of a place
+        (from a supported place API, e.g. Foursquare), a group of users, and
+        some wait lists.
+
+        The users associated with the restaurant represent the staff and are
+        able to manage the restaurant's wait lists, i.e. create or cancel
+        reservations on behalf of other users or mark reservations as "seated",
+        "no show" or "bumped".
+
+        ### Wait List
+
+        The **wait list** is the primary resource. A wait list belongs to a
+        restaurant, has an ordered list of reservations, along with the
+        following attributes:
+
+        * _table_size_ - the number of people who can be seated at this
+        wait list's tables. A restaurant should have a wait list per
+        available table size per dining service.
+
+        * _reservations_start_ - when reservations can start being created
+        for this wait list. Once this time has passed, the wait list is
+        "open".
+
+        * _seating_start_ - when the first reservation on this wait list
+        will be seated. Once this time has passed, the wait list is
+        "active".
+
+        A wait list can be closed manually or automatically (based upon some
+        criteria, e.g. a reservation threshold). Once closed, reservations can
+        no longer be created for the wait list, and it will no longer show up in
+        search results.
+
+        ### Reservation
+
+        A **reservation** represents a patron's position on a wait list. A
+        reservation can have one of five states:
+
+        * _waiting_ - the patron has not yet been seated, or marked as a no
+        show.
+
+        * _cancelled_ - the patron has yet to be seated, but has removed
+        himself from the waitlist.
+
+        * _seated_ - the patron has been seated at his table.
+
+        * _no show_ - the patron did not show up for the meal.
+
+        * _bumped_ - the patron was on the wait list, but the restuarant
+        was unable to seat him, probably due to the end of service.
+
+        A patron can create a reservation for himself on any open wait
+        list, as long as he does not already have a reservation on another
+        wait list at "around the same time".
+
+        A patron can also remove himself from a wait list, causing his
+        reservation to be marked as either "cancelled" or "no show".
       DESC
     end
+
+    doc.get '/wait-lists' do
+      description 'Search by geolocation and party size'
+
+      authentication_required false
+
+      parameter 'latitude', 'The latitude near which the wait lists\' restaurants should be located',
+        type: 'number'
+      parameter 'longitude', 'The longitude near which the wait lists\' restaurants should be located',
+        type: 'number'
+      parameter 'table_size', 'The the number of people that the wait list\'s table accomodate',
+        type: 'integer'
+      parameter 'page', 'The page of results to be retrieved. 20 results are returned per page',
+        type: 'integer', required: false, default: 1
+
+      response 200, 'A list of wait lists was successfully returned' do
+        body do
+          content_type 'application/json'
+
+          attribute 'page', 'The page of results that was returned'
+          attribute 'total', 'The total number of wait lists matching the parameters'
+          attribute 'wait_lists', 'The list of wait lists matching the parameters, for the current page', type: 'array[object]' do
+            attribute 'restaurant', 'The restaurant associated with the wait list', type: 'object' do
+              attribute 'id', 'The unique ID of the restaurant', type: 'string'
+              attribute 'name', 'The name of the restaurant', type: 'string'
+              attribute 'latitude', 'The latitude of the restaurant', type: 'number'
+              attribute 'latitude', 'The longitude of the restaurant', type: 'number'
+            end
+            attribute 'reservations_start', 'The time that reservations can be created for this wait list', type: 'timestamp'
+            attribute 'estimated_seating_time', 'The time at which the next available reservation on the ' +
+              'wait list is estimated to be seated', type: 'timestamp'
+          end
+        end
+      end
+
+      response 422, 'latitude, longitude or table_size was omitted'
+      response 422, 'Invalid latitude - must be a number between -90 and 90'
+      response 422, 'Invalid longitude - must be a number between -180 and 180'
+      response 422, 'Invalid table_size - must be an integer greater than zero'
+      response 422, 'Invalid page - must be an integer greater than zero'
+    end
   end
 end

data/useless-wait-list.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
 
 Gem::Specification.new do |spec|
   spec.name           = 'useless-wait-list'
-  spec.version        = '0.0.2'
+  spec.version        = '0.0.3'
   spec.authors        = ['Kevin Hyland']
   spec.email          = ['khy@me.com']
   spec.summary        = 'For restaurants that don\'t take reservations'
@@ -18,7 +18,7 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency 'sinatra', '~> 1.4.2'
   spec.add_runtime_dependency 'useless', '~> 0.2.0'
-  spec.add_runtime_dependency 'useless-doc', '~> 0.6.4'
+  spec.add_runtime_dependency 'useless-doc', '~> 0.7'
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'rake', '~> 0.9'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: useless-wait-list
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Kevin Hyland
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-02 00:00:00.000000000 Z
+date: 2013-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sinatra
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.6.4
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: 0.6.4
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement