Add parameters description to each endpoint

BookingSync · Aug 25, 2014 · 6bdfc30 · 6bdfc30
1 parent eaf0ce5
commit 6bdfc30
Show file tree

Hide file tree

Showing 41 changed files with 1,160 additions and 370 deletions.
diff --git a/content/reference/endpoints/amenities.md b/content/reference/endpoints/amenities.md
@@ -3,6 +3,24 @@
 1. TOC
 {:toc}
 
+<ul class="nav nav-pills pull-right" role="tablist">
+  <li class="disabled"><a>OAuth Scopes:</a></li>
+  <li class="active"><a href="#public" role="tab" data-toggle="pill">public</a></li>
+</ul>
+
+<div class="tab-content" markdown="1">
+  <div class="tab-pane active" id="public" markdown="1">
+### Parameters
+
+Name             | Type    | Read/Write | Description
+-----------------|---------|------------|------------
+id               | Integer | Read       | Amenity's id.
+-----------------|---------|------------|------------
+title            | String  | Read       | Amenity's title.
+{: class="table table-bordered"}
+  </div>
+</div>
+
 ## List amenities
 
 List all amenities for given account(s). Amenities can repeat because each
@@ -12,8 +30,7 @@ rental has it's own set of amenities.
 GET /amenities
 ~~~
 
-<%= render 'json_response', endpoint: "amenities",
-  scopes: %w(public) %>
+<%= render 'json_response', endpoint: "amenities", scopes: %w(public) %>
 
 ## Get a single amenity
 
@@ -23,5 +40,4 @@ Returns a single amenity identified by ID.
 GET /amenities/:amenity_id
 ~~~
 
-<%= render 'json_response', endpoint: "amenities",
-  scopes: %w(public) %>
+<%= render 'json_response', endpoint: "amenities", scopes: %w(public) %>
diff --git a/content/reference/endpoints/billing_addresses.md b/content/reference/endpoints/billing_addresses.md
@@ -3,6 +3,36 @@
 1. TOC
 {:toc}
 
+<ul class="nav nav-pills pull-right" role="tablist">
+  <li class="disabled"><a>OAuth Scopes:</a></li>
+  <li class="active">
+    <a href="#payments_read-payments_write" role="tab" data-toggle="pill">
+      payments_read / payments_write
+    </a>
+  </li>
+</ul>
+
+<div class="tab-content" markdown="1">
+  <div class="tab-pane active" id="payments_read-payments_write" markdown="1">
+### Parameters
+
+Name             | Type    | Read/Write | Description
+-----------------|---------|------------|------------
+id               | Integer | Read       | Billing Address's id.
+-----------------|---------|------------|------------
+address1         | String  | Read       | Billing Address's first address.
+address2         | String  | Read       | Billing Address's second address.
+city             | String  | Read       | Billing Address's city.
+country_code     | String  | Read       | Billing Address's country_code, list of codes is available at [wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+state            | String  | Read       | Billing Address's state.
+zip              | String  | Read       | Billing Address's zip.
+-----------------|---------|------------|------------
+created_at       | [Time](/reference/formats#date--time) | Read       | Billing Address's create time.
+updated_at       | [Time](/reference/formats#date--time) | Read       | Billing Address's update time.
+{: class="table table-bordered"}
+  </div>
+</div>
+
 ## List billing addresses
 
 List all billing addresses for given account.

diff --git a/content/reference/endpoints/bookings.md b/content/reference/endpoints/bookings.md
@@ -3,6 +3,122 @@
 1. TOC
 {:toc}
 
+<ul class="nav nav-pills pull-right" role="tablist">
+  <li class="disabled"><a>OAuth Scopes:</a></li>
+  <li class="active"><a href="#public" role="tab" data-toggle="pill">public</a></li>
+  <li><a href="#bookings_public_write" role="tab" data-toggle="pill">bookings_public_write</a></li>
+  <li><a href="#bookings_read" role="tab" data-toggle="pill">bookings_read</a></li>
+  <li><a href="#bookings_write" role="tab" data-toggle="pill">bookings_write</a></li>
+</ul>
+
+<div class="tab-content" markdown="1">
+  <div class="tab-pane active" id="public" markdown="1">
+### Parameters
+
+Name                    | Type    | Read/Write | Description
+------------------------|---------|------------|------------
+id                      | Integer | Read       | Booking's id.
+------------------------|---------|------------|------------
+status                  | String  | Read       | Booking's status.
+------------------------|---------|------------|------------
+start_at                | [Time](/reference/formats#date--time) | Read       | Booking's start time.
+end_at                  | [Time](/reference/formats#date--time) | Read       | Booking's end time.
+updated_at              | [Time](/reference/formats#date--time) | Read       | Booking's update time.
+{: class="table table-bordered"}
+  </div>
+  <div class="tab-pane" id="bookings_public_write" markdown="1">
+### Parameters
+
+Name                    | Type    | Read/Write | Description
+------------------------|---------|------------|------------
+id                      | Integer | Read       | Booking's id.
+client_id               | Integer | Write      | **Required**. Client id related to the Booking.
+rental_id               | Integer | Write      | **Required**. Rental id related to the Booking.
+source_id               | Integer | Write      | Source id related to the Booking.
+------------------------|---------|------------|------------
+adults                  | Integer | Write      | Booking's number of adults.
+booked                  | Boolean | Write      | Booking's booked status.
+children                | Integer | Write      | Booking's number of children.
+currency                | String  | Write      | Booking's currency code, list of codes described in [enums section](/reference/enums#currencies).
+deposit                 | [Decimal](/reference/enums#formats) | Write      | Booking's deposit.
+discount                | String  | Write      | Booking's discount. (in percents e.g. 10%)
+final_price             | [Decimal](/reference/enums#formats) | Write      | Booking's final price. (after discount)
+initial_price           | [Decimal](/reference/enums#formats) | Write      | Booking's initial price.
+notes                   | Text    | Write      | Booking's notes. (1000 characters max)
+status                  | String  | Read       | Booking's status.
+unavailable             | Boolean | Write      | Booking's unavailable status.
+------------------------|---------|------------|------------
+tentative_expires_at    | [Time](/reference/formats#date--time) | Write      | Booking's tentative expiry time.
+start_at                | [Time](/reference/formats#date--time) | Read/Write | **Required**. Booking's start time.
+end_at                  | [Time](/reference/formats#date--time) | Read/Write | **Required**. Booking's end time.
+updated_at              | [Time](/reference/formats#date--time) | Read       | Booking's update time.
+{: class="table table-bordered"}
+  </div>
+  <div class="tab-pane" id="bookings_read" markdown="1">
+### Parameters
+
+Name                    | Type    | Read/Write | Description
+------------------------|---------|------------|------------
+id                      | Integer | Read       | Booking's id.
+------------------------|---------|------------|------------
+adults                  | Integer | Read       | Booking's number of adults.
+booked                  | Boolean | Read       | Booking's booked status.
+bookings_payments_count | Integer | Read       | Booking's number of payments.
+children                | Integer | Read       | Booking's number of children.
+currency                | String  | Read       | Booking's currency code, list of codes described in [enums section](/reference/enums#currencies).
+deposit                 | [Decimal](/reference/enums#formats) | Read       | Booking's deposit.
+discount                | String  | Read       | Booking's discount. (in percents e.g. 10%)
+final_price             | [Decimal](/reference/enums#formats) | Read       | Booking's final price. (after discount)
+initial_price           | [Decimal](/reference/enums#formats) | Read       | Booking's initial price.
+locked                  | String  | Read       | Booking's locked status.
+notes                   | Text    | Read       | Booking's notes.
+review_requests_count   | Integer | Read       | Booking's number of review requests.
+status                  | String  | Read       | Booking's status.
+unavailable             | Boolean | Read       | Booking's unavailable status.
+------------------------|---------|------------|------------
+canceled_at             | [Time](/reference/formats#date--time) | Read       | Booking's cancel time.
+tentative_expires_at    | [Time](/reference/formats#date--time) | Read       | Booking's tentative expiry time.
+start_at                | [Time](/reference/formats#date--time) | Read       | Booking's start time.
+end_at                  | [Time](/reference/formats#date--time) | Read       | Booking's end time.
+created_at              | [Time](/reference/formats#date--time) | Read       | Booking's create time.
+updated_at              | [Time](/reference/formats#date--time) | Read       | Booking's update time.
+{: class="table table-bordered"}
+  </div>
+  <div class="tab-pane" id="bookings_write" markdown="1">
+### Parameters
+
+Name                    | Type    | Read/Write | Description
+------------------------|---------|------------|------------
+id                      | Integer | Read       | Booking's id.
+client_id               | Integer | Write      | **Required**. Client id related to the Booking.
+rental_id               | Integer | Write      | **Required**. Rental id related to the Booking.
+source_id               | Integer | Write      | Source id related to the Booking.
+------------------------|---------|------------|------------
+adults                  | Integer | Read/Write | Booking's number of adults.
+booked                  | Boolean | Read/Write | Booking's booked status.
+bookings_payments_count | Integer | Read       | Booking's number of payments.
+children                | Integer | Read/Write | Booking's number of children.
+currency                | String  | Read/Write | Booking's currency code, list of codes described in [enums section](/reference/enums#currencies).
+deposit                 | [Decimal](/reference/enums#formats) | Read/Write | Booking's deposit.
+discount                | String  | Read/Write | Booking's discount. (in percents e.g. 10%)
+final_price             | [Decimal](/reference/enums#formats) | Read/Write | Booking's final price. (after discount)
+initial_price           | [Decimal](/reference/enums#formats) | Read/Write | Booking's initial price.
+locked                  | String  | Read/Write | Booking's locked status.
+notes                   | Text    | Read/Write | Booking's notes. (1000 characters max)
+review_requests_count   | Integer | Read       | Booking's number of review requests.
+status                  | String  | Read       | Booking's status.
+unavailable             | Boolean | Read/Write | Booking's unavailable status.
+------------------------|---------|------------|------------
+canceled_at             | [Time](/reference/formats#date--time) | Read       | Booking's cancel time.
+tentative_expires_at    | [Time](/reference/formats#date--time) | Read/Write | Booking's tentative expiry time.
+start_at                | [Time](/reference/formats#date--time) | Read/Write | **Required**. Booking's start time.
+end_at                  | [Time](/reference/formats#date--time) | Read/Write | **Required**. Booking's end time.
+created_at              | [Time](/reference/formats#date--time) | Read       | Booking's create time.
+updated_at              | [Time](/reference/formats#date--time) | Read       | Booking's update time.
+{: class="table table-bordered"}
+  </div>
+</div>
+
 ## List bookings
 
 Based on the OAuth token scopes bookings listing will be limited to a
@@ -35,7 +151,7 @@ Example:
 GET /bookings?status=booked,unavailable&from=20140324
 ~~~
 
-### Parameters
+### Search Parameters
 
 Name             | Type    | Default | Description
 -----------------|---------|--------------
@@ -59,3 +175,41 @@ GET /bookings/:booking_id
 
 <%= render 'json_response', endpoint: "bookings",
   scopes: %w(public-bookings_public_write bookings_read-bookings_write) %>
+
+## Create a new booking
+
+Creates a booking for given rental.
+
+~~~~
+POST /rentals/:rental_id/bookings
+~~~~
+
+<%= render 'json_response', endpoint: "bookings", request: "request",
+  scopes: [
+    { bookings_public_write: "public-bookings_public_write" },
+    { bookings_write: "bookings_read-bookings_write" }
+  ] %>
+
+## Update a booking
+
+Returns an updated booking identified by ID.
+
+~~~
+PUT /bookings/:booking_id
+~~~
+
+<%= render 'json_response', endpoint: "bookings", request: "request",
+  scopes: [
+    { bookings_public_write: "public-bookings_public_write" },
+    { bookings_write: "bookings_read-bookings_write" }
+  ] %>
+
+## Cancel a booking
+
+Required OAuth scope: `:bookings_write` or `:bookings_public_write`
+
+Returns an empty response with '204 No Content' status code on success.
+
+~~~~~~
+DELETE /bookings/:booking_id
+~~~~~~
diff --git a/content/reference/endpoints/bookings_payments.md b/content/reference/endpoints/bookings_payments.md
@@ -3,6 +3,30 @@
 1. TOC
 {:toc}
 
+<ul class="nav nav-pills pull-right" role="tablist">
+  <li class="disabled"><a>OAuth Scopes:</a></li>
+  <li class="active"><a href="#payments_read-payments_write" role="tab" data-toggle="pill">
+    payments_read / payments_write
+  </a></li>
+</ul>
+
+<div class="tab-content" markdown="1">
+  <div class="tab-pane active" id="payments_read-payments_write" markdown="1">
+### Parameters
+
+Name             | Type    | Read/Write | Description
+-----------------|---------|------------|------------
+id               | Integer | Read       | Bookings Payment's id.
+-----------------|---------|------------|------------
+amount           | Integer | Read       | Bookings Payment's amount.
+currency         | String  | Read       | Bookings Payment's currency code, list of codes described in [enums section](/reference/enums#currencies).
+-----------------|---------|------------|------------
+created_at       | [Time](/reference/formats#date--time) | Read       | Bookings Payment's create time.
+updated_at       | [Time](/reference/formats#date--time) | Read       | Bookings Payment's update time.
+{: class="table table-bordered"}
+  </div>
+</div>
+
 ## List bookings payments
 
 <%= render 'amount_callout' %>

diff --git a/content/reference/endpoints/clients.md b/content/reference/endpoints/clients.md
@@ -3,6 +3,63 @@
 1. TOC
 {:toc}
 
+<ul class="nav nav-pills pull-right" role="tablist">
+  <li class="disabled"><a>OAuth Scopes:</a></li>
+  <li class="active"><a href="#clients_read" role="tab" data-toggle="pill">clients_read</a></li>
+  <li><a href="#clients_write" role="tab" data-toggle="pill">clients_write</a></li>
+</ul>
+
+<div class="tab-content" markdown="1">
+  <div class="tab-pane active" id="clients_read" markdown="1">
+### Parameters
+
+Name             | Type    | Read/Write | Description
+-----------------|---------|------------|------------
+id               | Integer | Read       | Client's id.
+-----------------|---------|------------|------------
+address1         | String  | Read       | Client's first address.
+address2         | String  | Read       | Client's second address.
+city             | String  | Read       | Client's city.
+country_code     | String  | Read       | Client's country code, list of codes is available at [wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+email            | String  | Read       | Client's email.
+fax              | String  | Read       | Client's fax.
+fullname         | String  | Read       | Client's fullname.
+mobile           | String  | Read       | Client's mobile.
+notes            | Text    | Read       | Client's notes.
+phone            | String  | Read       | Client's phone.
+state            | String  | Read       | Client's state.
+zip              | String  | Read       | Client's zip.
+-----------------|---------|------------|------------
+created_at       | [Time](/reference/formats#date--time) | Read       | Client's create time.
+updated_at       | [Time](/reference/formats#date--time) | Read       | Client's update time.
+{: class="table table-bordered"}
+  </div>
+  <div class="tab-pane" id="clients_write" markdown="1">
+### Parameters
+
+Name             | Type    | Read/Write | Description
+-----------------|---------|------------|------------
+id               | Integer | Read       | Client's id.
+-----------------|---------|------------|------------
+address1         | String  | Read/Write | Client's first address.
+address2         | String  | Read/Write | Client's second address.
+city             | String  | Read/Write | Client's city.
+country_code     | String  | Read/Write | Client's country code, list of codes is available at [wikipedia](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
+email            | String  | Read/Write | Client's email.
+fax              | String  | Read/Write | Client's fax.
+fullname         | String  | Read/Write | **Required**. Client's fullname. (150 characters max)
+mobile           | String  | Read/Write | Client's mobile.
+notes            | Text    | Read/Write | Client's notes. (1000 characters max)
+phone            | String  | Read/Write | Client's phone.
+state            | String  | Read/Write | Client's state.
+zip              | String  | Read/Write | Client's zip.
+-----------------|---------|------------|------------
+created_at       | [Time](/reference/formats#date--time) | Read       | Client's create time.
+updated_at       | [Time](/reference/formats#date--time) | Read       | Client's update time.
+{: class="table table-bordered"}
+  </div>
+</div>
+
 ## List clients
 
 List all clients for given account.
@@ -11,8 +68,7 @@ List all clients for given account.
 GET /clients
 ~~~
 
-<%= render 'json_response', endpoint: "clients",
-  scopes: %w(clients_read-clients_write) %>
+<%= render 'json_response', endpoint: "clients", scopes: %w(clients_read-clients_write) %>
 
 ## Get a single client
 
@@ -22,5 +78,26 @@ Returns a single client identified by ID.
 GET /clients/:client_id
 ~~~
 
-<%= render 'json_response', endpoint: "clients",
-  scopes: %w(clients_read-clients_write) %>
+<%= render 'json_response', endpoint: "clients", scopes: %w(clients_read-clients_write) %>
+
+## Create a new client
+
+Returns a newly created client.
+
+~~~~
+POST /clients
+~~~~
+
+<%= render 'json_response', endpoint: "clients", request: "request",
+  scopes: [{ clients_write: "clients_read-clients_write" }] %>
+
+## Update a client
+
+Returns an updated client identified by ID.
+
+~~~
+PUT /clients/:client_id
+~~~
+
+<%= render 'json_response', endpoint: "clients", request: "request",
+  scopes: [{ clients_write: "clients_read-clients_write" }] %>