adding uss blobs

Signed-off-by: Christopher Guindon <chris.guindon@eclipse-foundation.org>

src/index.apib

@@ -7,6 +7,37 @@ Eclipse Fountation resources and data.
 ### Rate Limit
 This API currently limits users to 1000 authenticated requests and 1000 anonymous requests an hour.
 
+### Pagination
+Information about pagination is provided in the Link header of an API call. For example, let’s make 
+a curl request to the eclipse_profile API, to find out how many org_eclipse_oomph records exist for the user:
+ 
+```curl -I "https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&pagesize=2"```
+ 
+The -I parameter indicates that we only care about the headers, not the content. 
+In examining the result, you’ll notice some information in the Link header that looks like this:
+ 
+```<https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=2&amp;pagesize=2>; rel="next", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=27&amp;pagesize=2>; rel="last", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&amp;pagesize=2>; rel="first", <https://api.eclipse.org/api/blob/KJBNCEW08231nkJKCEW32898239?page=1&amp;pagesize=2>; rel="self"```
+ 
+Let’s break that down. rel="next" says that the next page is page=2. This makes sense, since by default, 
+all paginated queries start at page 1. rel="last" provides some more information, stating that the last page of results is on page 27. 
+ 
+Keep in mind that you should always rely on these link relations provided to you. Don’t try to guess or construct your own URL.
+
+### Caching
+
+Most responses return an ETag header. You can use the values of these headers to make subsequent 
+requests to those resources using the If-None-Match or if-Match header. For example, if the resource 
+has not changed on a GET, the server will return a 304 Not Modified.
+ 
+The Etag for a blob resource is predictable. This is how were are currently generating them:
+
+```
+function _generate_etag($value, $application_token, $key) {
+  $string = $value . $application_token . $key;
+  return  hash('sha256', $string, FALSE);
+}
+```
+
 ### Authentication
 *Eclipse Api RESTful API* uses OAuth2 Authorization for protected resources.
 
@@ -15,6 +46,7 @@ The common [HTTP Response Status Codes](https://github.com/for-GET/know-your-htt
 are used.
 
 <!-- include(modules/account.apib) -->
+<!-- include(modules/uss.apib) -->
 <!-- include(modules/download.apib) -->
 <!-- include(modules/marketplace_favorites.apib) -->
 <!-- include(modules/oauth2.apib) -->

src/modules/download.apib

 # Group Download
 Download files and release information.
 
-## Retrive user [GET /download/file/{file_id}]
+## Retrieve File [GET /download/file/{file_id}]
 Fetch download file information.
 
 + Parameters
@@ -16,7 +16,7 @@ Fetch download file information.
     + Body
        {"file_id":"213","file_name":"/stats/releases/mars/org.eclipse.oomph.setup.sdk","download_count":"4499","size_disk_bytes":"0","timestamp_disk":"0","md5sum":"nofile","sha1sum":"nofile","sha512sum":"nofile"}
 
-## Releases [GET /download/release/{release_type}{?release_name,release_version}]
+## Release [GET /download/release/{release_type}{?release_name,release_version}]
 Fetch download file information.
 
 + Parameters

src/modules/uss.apib

+# Group Eclipse USS
+The Eclipse User Storage Service (USS) allows Eclipse projects to store user-specific project information on the 
+Eclipse Foundation servers. The goal is to make it easy for our projects to offer a 
+better user experience by storing relevant information in a central location.
+
+The BLOB resource is a way for projects to store binary objects based off a application_token/key value pair.
+ 
+The “value” is always the last element in this JSON structure. All other things must come before that so that 
+the SDK implementation can parse and collect them into a Map and finally return a decoding InputStream to 
+deliver the “value” content back to the caller/application. The blob value is available when the 
+client retrieve a specific blob using an application_token and key.
+ 
+We are using application_token and key to identify a blob. The Application token is a string that is assigned by the 
+Eclipse Management Organization.The key string must respect the following validation rules: 
+
+* 5-25 characters;
+* letters: lowercase and uppercase/numbers/underscores are valid;
+* each string should start with a letter.
+
+## Fetch Blobs [GET /uss/blob{?page,pagesize}]
+Retrieve a list of all the blobs for a user. Requires the `uss_retrieve` scope.
+
++ Parameters
+    + page (integer, optional) - The index of the page to get, defaults to 1.
+    + pagesize (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+
++ Request
+    + Headers
+        Authorization: Bearer ec342fe0d66baab3c4b42549f
+        Accept: application/json
+        User-Agent: USER_AGENT
+        Accept: application/json
+        Content-Type: application/json
+
++ Response 401 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/json
+        
++ Response 200 (application/json)
+    + Headers
+        Link: <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="last", <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="first", <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="self"
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/json
+
+    + Body
+        [{"application_token":"MZ04RMOpksKN5GpxKXafq2MSjSP","etag":"9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb","changed":"1497030093","key":"mpc_favorites","url":"https://api.eclipse.org/account/profile/1/blob/MZ04RMOpksKN5GpxKXafq2MSjSP/mpc_favorites"}]
+        
+## Search Blobs [GET /uss/blob/{application_token}/{blob_key}{?page,pagesize}]
+Search specific user blob object. Requires the `uss_retrieve` scope.
+
++ Parameters
+    + `application_token` (string, required) - Unique identifer of the project, i.e, eclipse.org.oomph.
+    + `blob_key` (string, optional) - Unique identifier of the profile setting to save, i.e, install_xml.
+    + `page` (integer, optional) - The index of the page to get, defaults to 1.
+    + `pagesize` (integer, optional) - The number of records to get per page, defaults to 20. Maximum value is 100.
+
++ Request
+    + Headers
+        Authorization: Bearer ec342fe0d66baab3c4b42549f
+        Accept: application/json
+        User-Agent: USER_AGENT
+        If-None-Match: 54d66cdf0a31cf65bf3f6c9888fc3efdd51dd079f5da4200d7e6ccb399b25a61
+        Accept: application/json
+        Content-Type: application/json
+        If-Modified-Since: Wed, 21 Oct 2015 07:28:00 GMT
+
++ Response 401 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/json
+        
+        
++ Response 304 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Etag: "9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb"
+        Content-Type: application/json
+        
++ Response 200 (application/json)
+    + Headers
+        Link: <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="last", <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="first", <https://api.eclipse.org/uss/blob?page=1&amp;pagesize=20>; rel="self"
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Etag: "9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb"
+        Content-Type: application/json
+        
+    + Body
+      {"application_token":"MZ04RMOpksKN5GpxKXafq2MSjSP","etag":"9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb","changed":"1497030093","key":"mpc_favorites","url":"https://api.eclipse.local:51243/account/profile/1/blob/MZ04RMOpksKN5GpxKXafq2MSjSP/mpc_favorites","value":"MzI3NDQwNQ=="}
+
+## Delete Blobs [DELETE /uss/blob/{application_token}/{blob_key}]
+Delete a blob for a user. Requires the `uss_update` scope.
+
++ Parameters
+    + `application_token` (string, required) - Unique identifer of the project, i.e, eclipse.org.oomph.
+    + `blob_key` (string, optional, required) - Unique identifier of the profile setting to save, i.e, install_xml.
+    
++ Request
+    + Headers
+        Authorization: Bearer ec342fe0d66baab3c4b42549f
+        Accept: application/json
+        User-Agent: USER_AGENT
+        If-None-Match: 54d66cdf0a31cf65bf3f6c9888fc3efdd51dd079f5da4200d7e6ccb399b25a61
+        Accept: application/json
+        Content-Type: application/json
+        
++ Response 401 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/js
+        
++ Response 204 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/js
+        
+## Update/Create Blobs [PUT /uss/blob/{application_token}/{blob_key}]
+Delete a blob for a user. Requires the `uss_update` scope.
+
++ Parameters
+    + `application_token` (string, required) - Unique identifer of the project, i.e, eclipse.org.oomph.
+    + `blob_key` (string, optional, required) - Unique identifier of the profile setting to save, i.e, install_xml.
+    
++ Request
+    + Headers
+        Authorization: Bearer ec342fe0d66baab3c4b42549f
+        Accept: application/json
+        User-Agent: USER_AGENT
+        If-Match: 54d66cdf0a31cf65bf3f6c9888fc3efdd51dd079f5da4200d7e6ccb399b25a61
+        Accept: application/json
+        Content-Type: application/json
+        
++ Response 401 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/js
+        
++ Response 201 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/js
+        Etag: "9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb"
+        
+    + Body
+       {"url":"https://api.eclipse.org/api/blob/:namespace/:key"}
+        
++ Response 200 (application/json)
+    + Headers
+        X-Rate-Limit-Limit: 1000
+        X-Rate-Limit-Remaining: 964
+        X-Rate-Limit-Reset: 3553
+        Content-Type: application/js
+        Etag: "9f76b4dde4cb5146daa5686a7f4376084dbe41bf9c9d4a12b722fe1062eb48eb"
\ No newline at end of file