Move blueprints into docs/api and split into multiple files

Author: rjmackay

apiary.apib

@@ -0,0 +1,82 @@
+# Group Authorization with OAuth 2
+
+Most API requests are authenticated with OAuth2.
+
+## OAuth 2 token exchange [/api/v3/oauth/token]
+The first step of OAuth is to exchange credentials for an `access_token`. This `access_token` is then used on subsequent resource requests.
+
+Supported grant types:
+
++ `client_credentials`
++ `password`
+
+### Exchange credentials for token [POST]
++ Request Client Credentials grant
+    + Attributes (OAuth grant request)
+    + Headers
+
+            Authorization: Basic ABCDEF
+
++ Response 200 (application/json)
+    + Attributes (OAuth valid response)
+
++ Request Password grant
+    + Attributes (OAuth password grant request)
+
++ Response 200 (application/json)
+    + Attributes (OAuth valid response)
+
+## Accessing a protected resource [/api/v3/protected]
+
+Now we have an `access_token` we add that to the `Authentication` header on all resource requests.
+
+### Accessing a protected resource [GET]
++ Request With Valid token
+    + Headers
+
+            Authentication: Bearer accesstoken
+
++ Response 200 (application/json)
+    + Attributes (Server response)
+
+
++ Request With Invalid or Expired token
+    + Headers
+
+            Authentication: Bearer invalidOrExpireToken
+
++ Response 401 (application/json)
+    + Attributes (Server error response)
+
++ Request With insufficient permissions
+    + Headers
+
+            Authentication: Bearer accesstoken
+
++ Response 403 (application/json)
+    + Attributes (Server error response)
+
+# Data Structures
+
+## OAuth grant request (object)
++ `grant_type`: `client_credentials` (string, required)
++ `client_id` (string, required)
++ `client_secret` (string, required)
++ `scope`: post,user(string, optional)
+
+## OAuth password grant request (object)
++ `grant_type`: `password` (string, required)
++ `client_id` (string, required)
++ `client_secret` (string, required)
++ `username`: [email protected] (string, required)
++ `password`: somepassword (string, required)
++ `scope`: post,user (string, optional)
+
+## OAuth valid response (object)
++ `access_token`: `eyJhbGciOiJIUzI1NiJ9` (string, required) - valid access token
++ scope: all (string, required) - scopes of current token
++ `expires_in`: 300 (number, required)
++ `token_type`: Bearer (string, required)
+
+## Server response (object)
++ status: ok (string, required)

docs/api/auth.apib

@@ -0,0 +1,43 @@
+
+# Group Collections
+
+## Collections [/api/v3/collections]
+
+### List All Collections [GET]
+
++ Response 200
+
+### Create a Collection [POST]
+
++ Response 200
+
+### Get a Collection [GET /api/v3/collections/{id}]
+
++ Response 200
+
+### Update a Collection [PUT /api/v3/collections/{id}]
+
++ Response 200
+
+### Delete a Collection [DELETE /api/v3/collections/{id}]
+
++ Response 200
+
+
+## Collection Posts [/api/v3/collections/{id}/posts]
+
+### Add a Post to a collection [POST]
+
++ Response 200
+
+### Get a Post in a collection [GET]
+
++ Response 200
+
+# Group Saved Searches
+
+## Saved Searches [/api/v3/savedsearches]
+
+### List All [GET]
+
++ Response 200

docs/api/collections.apib

@@ -0,0 +1,16 @@
+
+# Group Config
+
+## Config [/api/v3/config]
+
+### List All Config Groups [GET]
+
++ Response 200
+
+### Get a Config Group [GET /api/v3/config/{id}]
+
++ Response 200
+
+### Update a Config Group [PUT /api/v3/config/{id}]
+
++ Response 200

docs/api/config.apib

@@ -0,0 +1,10 @@
+
+# Group Data Providers
+
+### List All Data Providers [GET /api/v3/dataproviders]
+
++ Response 200
+
+### Get a Data Provider [GET /api/v3/dataproviders/{id}]
+
++ Response 200

docs/api/dataproviders.apib

@@ -0,0 +1,84 @@
+
+# Group Forms
+
+## Forms [/api/v3/forms]
+
+### List All Forms [GET]
+
++ Response 200 (application/json)
+
+
+### Create a Form [POST]
+
++ Response 200 (application/json)
+
+
+### Get a Form [GET /api/v3/forms/{id}]
+
++ Response 200 (application/json)
+
+
+### Update a Form [PUT /api/v3/forms/{id}]
+
++ Response 200 (application/json)
+
+
+### Delete a Form [DELETE /api/v3/forms/{id}]
+
++ Response 200 (application/json)
+
+
+
+## Form Attributes [/api/v3/forms/{formid}/attributes]
+
+### List All Form Attributes [GET]
+
++ Response 200 (application/json)
+
+
+### Create a Form Attributes [POST]
+
++ Response 200 (application/json)
+
+
+### Get a Form Attributes [GET /api/v3/forms/{formid}/attributes/{id}]
+
++ Response 200 (application/json)
+
+
+### Update a Form Attributes [PUT /api/v3/forms/{formid}/attributes/{id}]
+
++ Response 200 (application/json)
+
+
+### Delete a Form Attributes [DELETE /api/v3/forms/{formid}/attributes/{id}]
+
++ Response 200 (application/json)
+
+
+
+## Form Stages [/api/v3/forms/{formid}/stages]
+
+### List All Form Stages [GET]
+
++ Response 200 (application/json)
+
+
+### Create a Form Stage [POST]
+
++ Response 200 (application/json)
+
+
+### Get a Form Stage [GET /api/v3/forms/{formid}/stages/{id}]
+
++ Response 200 (application/json)
+
+
+### Update a Form Stage [PUT /api/v3/forms/{formid}/stages/{id}]
+
++ Response 200 (application/json)
+
+
+### Delete a Form Stage [DELETE /api/v3/forms/{formid}/stages/{id}]
+
++ Response 200 (application/json)

docs/api/forms.apib

@@ -0,0 +1,30 @@
+
+
+# Group Import
+
+## CSV [/api/v3/csv]
+
+### List All [GET]
+
++ Response 200 (application/json)
+
+### Upload a CSV [POST]
+
++ Response 200 (application/json)
+
+### Get CSV [GET /api/v3/csv/{id}]
+
++ Response 200 (application/json)
+
+### Update CSV [PUT /api/v3/csv/{id}]
+
++ Response 200 (application/json)
+
+### Delete CSV [DELETE /api/v3/csv/{id}]
+
++ Response 200 (application/json)
+
+### Import a CSV [POST /api/v3/csv/{id}/import]
+
++ Response 200 (application/json)
+

docs/api/import.apib

@@ -0,0 +1,59 @@
+FORMAT: 1A
+HOST: http://demo.api.ushahidi.io
+
+# Ushahidi Platform API
+
+Ushahidi is a tool to collect and manage citizen reports. This describes the resources that make up the Ushahidi Platform API v3. If you have any problems or requests please contact [support](mailto:[email protected]).
+
+<!-- include(overview.apib) -->
+
+<!-- include(auth.apib) -->
+
+<!-- include(posts.apib) -->
+
+<!-- include(media.apib) -->
+
+<!-- include(tags.apib) -->
+
+<!-- include(collections.apib) -->
+
+<!-- include(savedsearches.apib) -->
+
+<!-- include(import.apib) -->
+
+<!-- include(forms.apib) -->
+
+<!-- include(messages.apib) -->
+
+<!-- include(users.apib) -->
+
+<!-- include(config.apib) -->
+
+<!-- include(dataproviders.apib) -->
+
+<!-- include(migrations.apib) -->
+
+## Data Structures
+
+## Server error response (object)
++ errors (array, required)
+    + (object)
+        + status (number, required)
+        + title (string, required)
+
+## Not Found error response (object)
++ errors (array, required)
+    + (object)
+        + status: 404 (number, required)
+        + title: Resource could not be found (string, required)
+
+## Validation error response (object)
++ errors (array, required)
+    + (object)
+        + status: 422 (number, required)
+        + title: Validation Error (string, required)
+    + (object)
+        + status: 422 (number, required)
+        + title: Field is required (string, required)
+        + source (object)
+            + pointer: /field (string)