From 25d9004270f8fea3c44600f46d10d64bfeb799fd Mon Sep 17 00:00:00 2001 From: Randy Jung Date: Fri, 21 Sep 2012 17:10:18 -0700 Subject: [PATCH] properties draft --- comment.md | 3 + file.md | 3 + page.md | 3 + property.md | 165 ++++++++++++++++++++++++++++++++++++++++++++++++++- task.md | 1 + workspace.md | 3 + 6 files changed, 177 insertions(+), 1 deletion(-) diff --git a/comment.md b/comment.md index 215ea8c..96cc7eb 100644 --- a/comment.md +++ b/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. diff --git a/file.md b/file.md index da7264b..8723b1c 100644 --- a/file.md +++ b/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. diff --git a/page.md b/page.md index d8e169e..2978dfd 100644 --- a/page.md +++ b/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. diff --git a/property.md b/property.md index cb70b74..8dce13f 100644 --- a/property.md +++ b/property.md @@ -1,4 +1,167 @@ Properties ===================== -> Custom properties for workspaces. \ No newline at end of file +> 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. \ No newline at end of file diff --git a/task.md b/task.md index 08f38ff..a621600 100644 --- a/task.md +++ b/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. diff --git a/workspace.md b/workspace.md index 03c14fb..b51297e 100644 --- a/workspace.md +++ b/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.