properties draft

comment.md

@@ -78,6 +78,9 @@ Each comment will have `comments` which contains all the replies written for the
 
 More filtering options are available:
 
+* `GET /comments?page=2` to get the page two of results. The result will be paginated 30 items per page.
+* `GET /comments?order_by=updated_at+desc` will return sorted results by `updated_at` field.
+* `GET /comments?order_by=created_at+desc` will return sorted results by `created_at` field.
 * `GET /comments?commented_on_type=Workspace` will only return comments written for a workspace. Other parameters can be `File`, `Page` or `Comment`.
 * `GET /comments?commented_on_type=File&commented_on_ids=1,2,3` will return comments written for file 1, file 2 or file 3. `commented_on_ids` parameter will only work with `commented_on_type` parameter present.
 * `GET /comments?created_since=2012-09-18T18:11:40-07:00` will return comments which were created after given time.

file.md

@@ -72,6 +72,9 @@ If the user has no permission to access the workspace, server will return `403 F
 
 More filtering options are available:
 
+* `GET /files?page=2` to get the page two of results. The result will be paginated 30 items per page.
+* `GET /files?order_by=updated_at+desc` will return sorted results by `updated_at` field.
+* `GET /files?order_by=created_at+desc` will return sorted results by `created_at` field.
 * `GET /files?created_since=2012-09-18T18:11:40-07:00` will return files created after given time.
 * `GET /files?updated_since=2012-09-18T18:11:40-07:00` will return files updated after given time.
 * `GET /files?owner_ids=1,2,9` will return files which have owner 1 or owner 2 or owner 9.

page.md

@@ -56,6 +56,9 @@ If a page has share_mode of `anyone`, `expire_at` and `password` options will be
 
 More filtering options are available for `GET /pages`:
 
+* `GET /pages?page=2` to get the page two of results. The result will be paginated 30 items per page.
+* `GET /pages?order_by=updated_at+desc` will return sorted results by `updated_at` field.
+* `GET /pages?order_by=created_at+desc` will return sorted results by `created_at` field.
 * `GET /pages?created_since=2012-09-18T18:11:40-07:00` will return pages which were created after given time.
 * `GET /pages?updated_since=2012-09-18T18:11:40-07:00` will return pages which were updated after given time.
 * `GET /pages?owner_ids=1,2,9` will return pages which have owner's id of 1 or 2 or 9.

property.md

@@ -1,4 +1,167 @@
 Properties
 =====================
 
-> Custom properties for workspaces.
+> 5 types of custom properties are `text`, `pulldown`, `multi`, `boolean` or `date`.
+
+Get Properties
+--------------
+
+* `GET /workspaces/1/properties` will return all properties defined in the workspace. Response would look like this:
+
+```json
+[
+  {
+    "property": {
+      "id": 275,
+      "kind": "multi",
+      "name": "Select best three things about TeamPlatform",
+      "description": "not needed to be just three",
+      "selections": "Uniqueness, Fits my needs, Affordable, Support, Easy to use, All of the above",
+      "required_for": "create",
+      "required": true,
+      "team_id": 138,
+      "values_count": 2,
+      "created_at": "2011-06-14T12:33:51-07:00",
+      "updated_at": "2011-06-14T12:34:26-07:00"
+    },
+    "value": {
+      "id": 1868,
+      "value": "All of the above",
+      "property_id": 275,
+      "position": 1,
+      "target_type": "Workspace"
+      "target_id": 1127,
+      "created_at": "2011-06-14T12:33:51-07:00",
+      "updated_at": "2011-06-14T12:33:51-07:00"
+    }
+  },
+  {} ...more properties
+]
+```
+
+* `GET /properties` will return all properties defined for the team. Response will look similar to above case but will not have `value` part. `value` is only available when the property is added to workspaces and requested from `GET /workspaces/1/properties`.
+
+```json
+[
+  {
+    "property": {
+      "id": 275,
+      "kind": "multi",
+      "name": "Select best three things about TeamPlatform",
+      "description": "not needed to be just three",
+      ...property info
+    }
+    ...no value info here
+  },
+  {} ...more properties
+]
+```
+
+**Property**
+`selections` is comma separated list of possible choices for `pulldown` and `multi` type of properties.
+`required_for` with `create` means that this property field will be prompted to the user when a new workspace is going to be created from the workspace template which this property belongs to. `required` tells this property is required field to enter when presented to the user.
+`team_id` is the id of the team which owns this property.
+`values_count` goes up by one whenever this property is added to workspaces.
+
+**Value**
+`value` portion of the above example has the actual user input for the property. In the above example, user selected the `All of the above` from the property's selections.
+`property_id` points to the property definition which id is `275` in this case.
+`position` denotes the position of this property-value pair in the target workspace.
+`target_type` and `target_id` tells where this property-value pair exists.
+
+Get Property
+------------
+
+* `GET /workspaces/1/properties/1` returns single property-value pair like this:
+
+```json
+{
+  "property": {
+    "id": 275,
+    "kind": "multi",
+    "name": "Select best three things about TeamPlatform",
+    ...more info on property
+  },
+  "value": {
+    "id": 1868,
+    "value": "All of the above",
+    "property_id": 275,
+    ...more info on value
+  }
+}
+```
+
+* `GET /properties/1`
+
+```json
+{
+  "property": {
+    "id": 275,
+    "kind": "multi",
+    "name": "Select best three things about TeamPlatform",
+    ...more info on property
+  }
+  ...no value here
+}
+```
+
+Create Property
+----------------
+
+* `POST /workspaces/1/properties` with JSON:
+
+```json
+{
+  "kind": "pulldown",
+  "name": "Rate this workspace!",
+  "description": "in terms of contents quality",
+  "selections": "Super!, A+, A, A-, B+, B, B-, C, D",
+  "required_for": "create",
+  "required": true,
+  "value": "Super!",
+  "position": 1
+}
+```
+
+If workspace is present in the request uri and the workspace is accessible, Property-value pair will be created and will return `200 Ok` with created property-value pair.
+
+* `POST /properties` with JSON:
+
+```json
+{
+  "kind": "text",
+  "name": "What's your name?",
+  "description": "just out of curiosity",
+  "selections": "",
+  "required_for": "",
+  "required": false
+}
+```
+
+If workspace is not present, only new property will be created.
+
+Update Property
+---------------
+
+* `PUT /workspaces/1/properties/1` will update the property-value pair.
+
+```json
+{
+  "value": "D"
+}
+```
+
+* `PUT /properties/1` will only update the property attributes. Following JSON updates nothing.
+
+```json
+{
+  "value": "D",
+  "position": 2
+}
+```
+
+Delete Property
+----------------
+
+* `DELETE /properties/1` will delete property 1
+* `DELETE /workspaces/1/properties/1` will remove the property-value pair in workspace 1, but will not delete property 1 itself.

task.md

@@ -55,6 +55,7 @@ Task has three `state`s that are `created`, `started` and `finished`.
 
 More filtering options are available for `GET /tasks` and `GET /workspaces/1/tasks`:
 
+* `GET /tasks?page=2` to get the page two of results. The result will be paginated 30 items per page.
 * `GET /tasks?created_since=2012-09-18T18:11:40-07:00` will return tasks which were created after given time.
 * `GET /tasks?updated_since=2012-09-18T18:11:40-07:00` will return tasks which were updated after given time.
 * `GET /tasks?workspace_id=1` will return tasks in workspace 1.

workspace.md

@@ -56,6 +56,9 @@ Get Workspaces
 
 More filtering options are available for `GET /workspaces`:
 
+* `GET /workspaces?page=2` to get the page two of results. The result will be paginated 30 items per page.
+* `GET /workspaces?order_by=updated_at+desc` will return sorted results by `updated_at` field.
+* `GET /workspaces?order_by=created_at+desc` will return sorted results by `created_at` field.
 * `GET /workspaces?status=active` will return active workspaces.
 * `GET /workspaces?status=archived` will return archived workspaces.
 * `GET /workspaces?deleted=[true|false]` will return `deleted/not-deleted` workspaces.