├── README.md
└── v1
    ├── documentation
        ├── authentication.md
        ├── request.md
        └── response.md
    └── index.md


/README.md:
--------------------------------------------------------------------------------
1 | # Architecting an API
2 | 
3 | ## Versioning
4 | APIs should be properly versioned. APIs evolve and change, we must do this while supporting
5 | old versions. Otherwise, if you just change your API, a lot of your clients would be in trouble.
6 | Although, we won't be developing multiple versions (today we're working on V1), it is important
7 | that we plan for the future and properly namespace our documentation and work under V1 namespace.
8 | 


--------------------------------------------------------------------------------
/v1/documentation/authentication.md:
--------------------------------------------------------------------------------
 1 | # Authentication
 2 | 
 3 | ## API Key
 4 | 
 5 | Every user must obtain a public API key to make requests.
 6 | This key is sent in clear text along with every request.
 7 | 
 8 | The parameter name is `api_key`.
 9 | 
10 | ## API Secret Token
11 | 
12 | Every user receives a companion private secret token. This string is used as a
13 | salt in generating request signatures and is never sent in clear text.
14 | 
15 | The parameter name is `secret`.
16 | 


--------------------------------------------------------------------------------
/v1/documentation/request.md:
--------------------------------------------------------------------------------
  1 | # Requests
  2 | 
  3 | All requests are made on a specific API resource:
  4 | 
  5 |     https://api.aventura/v1/[resource]
  6 | 
  7 | The clear-text parameters in each requests must be accompanied by three
  8 | additional parameters: an _API key_, a _request signature_, and a _timestamp_.
  9 | The request signature is generated using a _secret token_, a _timestamp_.
 10 | 
 11 | ## Content Type
 12 | 
 13 | The body of POST and PUT requests, including any relevant parameters, can be
 14 | formatted as URL-encoded form data or Javascript Object Notation (JSON). The
 15 | format is specified in the `Content-Type` HTTP header of a request.
 16 | 
 17 | The API assumes that the body of a request is URL-encoded form data unless a
 18 | `Content-Type` header is specified. The following Content-Type headers are
 19 | accepted:
 20 | 
 21 | <table>
 22 |     <thead>
 23 |         <th>Format</th>
 24 |         <th>MIME Type</th>
 25 |     </thead>
 26 |     <tbody>
 27 |         <tr>
 28 |             <td>URL-encoded form data</td>
 29 |             <td>`application/x-www-form-urlencoded`</td>
 30 |         </tr>
 31 |         <tr>
 32 |             <td>JSON</td>
 33 |             <td>`application/json`</td>
 34 |         </tr>
 35 |     </tbody>
 36 | </table>
 37 | 
 38 | ## Request Validation
 39 | 
 40 | ### Timestamp
 41 | 
 42 | Every request must include a timestamp parameter with the UTC current date and time
 43 | in UNIX format. This parameter is both sent in clear text for verification
 44 | and included in the request signature as a salt. Requests submitted more than 10
 45 | minutes before or after the date and time indicated by the timestamp will be
 46 | rejected.
 47 | 
 48 | ### Endpoint
 49 | 
 50 | The endpoint -- the path to which the HTTP request is made -- is included only
 51 | as a parameter in the request signature as a salt.
 52 | 
 53 | ### Request Signature
 54 | 
 55 | Every request must include a request signature parameter, appended to the
 56 | clear-text parameters as rsig. This ensures that the request originated from an
 57 | authorized API user and, if applicable, that the user is authorized to perform
 58 | the requested action.
 59 | 
 60 | The request signature consists of the hexadecimal SHA-2 digest of the
 61 | alphabetized parameters in URL-encoded query string format. The parameters used
 62 | to construct the signature are all those that are required for the specific
 63 | request, including the API key, along with the requestor’s secret token, the
 64 | timestamp, the endpoint
 65 | 
 66 | #### Request Signature Parameters
 67 | <table>
 68 |     <thead>
 69 |         <th>Parameter Name</th>
 70 |         <th>Description</th>
 71 |         <th>Example</th>
 72 |     </thead>
 73 |     <tbody>
 74 |         <tr>
 75 |             <td><code>api_key</code></td>
 76 |             <td>The user’s API key.</td>
 77 |             <td><code>754a28309b20012f479b109add670a2c</code></td>
 78 |         </tr>
 79 |         <tr>
 80 |             <td><code>secret</code></td>
 81 |             <td>The API user’s secret token.</td>
 82 |             <td><code>003af2309b1f012f479b109add670a2c</code></td>
 83 |         </tr>
 84 |         <tr>
 85 |             <td><code>timestamp</code></td>
 86 |             <td>
 87 |                 The timestamp of the request in ISO 8601 format:
 88 |                 <code>YYYY-MM-DDThh:mmTZD</code>
 89 |             </td>
 90 |             <td><code>2012-04-18T21:02-07:00</code></td>
 91 |         </tr>
 92 |         <tr>
 93 |             <td><code>endpoint</code></td>
 94 |             <td>The path of the endpoint to which the API request is sent.</td>
 95 |             <td><code>/v1/resorts/48503</code></td>
 96 |         </tr>
 97 | 
 98 |         <tr>
 99 |             <td><em>Varies</em></td>
100 |             <td>All other clear-text parameters for the specific request.</td>
101 |             <td><code>api_key=754a28309b20012f479b109add670a2c&resort_id=2&package_id=10&</code></td>
102 |         </tr>
103 |     </tbody>
104 | </table>
105 | 
106 | For example, when making a call to retrieve information about a resort, the clear-text parameters would be
107 | 
108 | <table>
109 |     <thead>
110 |         <th>Parameter Name</th>
111 |         <th>Description</th>
112 |         <th>Example</th>
113 |     </thead>
114 |     <tbody>
115 |         <tr>
116 |             <td><code>api_key</code></td>
117 |             <td>The user’s API key.</td>
118 |             <td><code>754a28309b20012f479b109add670a2c</code></td>
119 |         </tr>
120 |         <tr>
121 |             <td><code>resort_id</code></td>
122 |             <td>The resort to fetch information about.</td>
123 |             <td><code>4832</code></td>
124 |         </tr>
125 |         <tr>
126 |             <td><code>timestamp</code></td>
127 |             <td>The timestamp of the request in ISO 8601 format: <code>YYYY-MM-DDThh:mmTZD</code></td>
128 |             <td><code>2014-04-18T21:12-00:00</code></td>
129 |         </tr>
130 |     </tbody>
131 | </table>
132 | 
133 | 
134 | As an example, to construct the request signature for this request, we start with the clear-text parameters in alphabetical order by name:
135 | 
136 |     api_key=754a28309b20012f479b109add670a2c&resort_id=4832
137 | 
138 | The secret token and timestamp are then added, in alphabetical order, as additional parameters. Then the whole string is URL-encoded:
139 | 
140 |     api_key=754a28309b20012f479b109add670a2c&endpoint=https%3A%2F%2Fapi.aventura%2Fv1%2Fresorts%2F48503&resort_id=4832&secret=003af2309b1f012f479b109add670a2c&timestamp=2014-04-18T21%3A12-00%3A00
141 | 
142 | And the final request signature would be the SHA-2 digest of the string above:
143 | 
144 |     681f9129c435e2af7c434c76e28db3921e1518956656d926f6124cc93a47c213
145 | 
146 | The signature is then appended as a parameter, `rsig`, to the clear-text query string. So the full request and return value would be
147 | 
148 |     GET https://api.aventura/v1/resorts/4832?api_key=754a28309b20012f479b109add670a2c&rsig=1d12d0b923ecdbb4d5b1df8c7f2f1b3c2270bc6e538bbf5d32611d3429c1b310&timestamp=2014-04-18T21%3A12-00%3A00
149 | 
150 |     => {
151 |             "name": "Resort Rio",
152 |             "url": "http://www.aventura/resorts/rio-hotel",
153 |             "description": "great resort in the heart of Rio",
154 |             ...
155 |         }
156 | 


--------------------------------------------------------------------------------
/v1/documentation/response.md:
--------------------------------------------------------------------------------
 1 | # Responses
 2 | 
 3 | Depending on its type, a request is either processed immediately or queued for
 4 | processing later. Generally, requests that are seeking information will get an
 5 | immediate response; requests that are modifying or adding data will be queued
 6 | for later.
 7 | 
 8 | ## Response Codes
 9 | 
10 | The following HTTP status codes are possible in response to a request:
11 | <table>
12 |     <thead>
13 |         <th>HTTP Status Code</th>
14 |         <th>Status</th>
15 |         <th>Description</th>
16 |     </thead>
17 |     <tbody>
18 |         <tr>
19 |             <td>200</td>
20 |             <td>OK (Immediate response)</td>
21 |             <td>The request was a success and the response includes the
22 |                 requested data.</td>
23 |         </tr>
24 |         <tr>
25 |             <td>202</td>
26 |             <td>OK (Immediate response)</td>
27 |             <td>The request was received and queued for processing, but not yet
28 |                 processed.</td>
29 |         </tr>
30 |         <tr>
31 |             <td>400</td>
32 |             <td>Bad Request</td>
33 |             <td>The request was malformed or unexpected.</td>
34 |         </tr>
35 |         <tr>
36 |             <td>401</td>
37 |             <td>Unauthorized</td>
38 |             <td>The request did not include a valid API key, secret, or resort
39 |                 authorization key.</td>
40 |         </tr>
41 |         <tr>
42 |             <td>403</td>
43 |             <td>Forbidden</td>
44 |             <td>The request included an API key, secret, or a resort
45 |                 authorization key that has been revoked.</td>
46 |         </tr>
47 |         <tr>
48 |             <td>404</td>
49 |             <td>Not Found</td>
50 |             <td>The requested resource was not found.</td>
51 |         </tr>
52 |         <tr>
53 |             <td>415</td>
54 |             <td>Unsupported Media Type</td>
55 |             <td>The request was sent with a specified format that is not
56 |                 supported.</td>
57 |         </tr>
58 |         <tr>
59 |             <td>429</td>
60 |             <td>Too Many Requests</td>
61 |             <td>The rate limit has been reached for this API key. See <em>Rate
62 |                 Limits</em>.</td>
63 |         </tr>
64 |         <tr>
65 |             <td>500</td>
66 |             <td>Internal Server Error</td>
67 |             <td>The request could not be fulfilled due to an unexpected
68 |                 error.</td>
69 |         </tr>
70 |         <tr>
71 |             <td>503</td>
72 |             <td>Service Unavailable</td>
73 |             <td>Aventura is temporarily unable to fulfill the request. The
74 |                 request can be tried again later.</td>
75 |         </tr>
76 |     </tbody>
77 | </table>
78 | 
79 | ## Response Format
80 | 
81 | All responses are sent in JSON.
82 | 


--------------------------------------------------------------------------------
/v1/index.md:
--------------------------------------------------------------------------------
 1 | * [Getting Started](getting_started.md)
 2 |     * Obtain an API Key and Secret Token
 3 |     * Rate Limits
 4 | * [Requests](requests.md)
 5 |     * Content Type
 6 |     * Request Validation
 7 |     * Timestamp
 8 |     * Endpoint
 9 |     * Request Signature
10 | * [Responses](responses.md)
11 |     * Response Codes
12 |     * Response Format
13 | * [Authentication](authentication.md)
14 |     * API Key
15 |     * API Secret Token
16 | * [Resources](resources.md)
17 |     * Products
18 |     * ...
19 | 


--------------------------------------------------------------------------------