-
Notifications
You must be signed in to change notification settings - Fork 41
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update memberships (remove subheader link on collections remove subj …
…links)
- Loading branch information
1 parent
ae625a1
commit a91954d
Showing
2 changed files
with
123 additions
and
169 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,201 +1,155 @@ | ||
| # Group Membership | ||
| Resources related to _Panoptes Group Memberships_ | ||
| # Memberships | ||
| ```json | ||
| { | ||
| "links": { | ||
| "memberships.user_group": { | ||
| "href": "/user_groups/{memberships.user_group}", | ||
| "type": "user_groups" | ||
| }, | ||
| "memberships.user": { | ||
| "href": "/users/{memberships.user}", | ||
| "type": "users" | ||
| } | ||
| }, | ||
| "meta": { | ||
| "memberships": { | ||
| "page": 1, | ||
| "page_size": 2, | ||
| "count": 28, | ||
| "include": [], | ||
| "page_count": 14, | ||
| "previous_page": 14, | ||
| "next_page": 2, | ||
| "first_href": "/memberships?page_size=2", | ||
| "previous_href": "/memberships?page=14page_size=2", | ||
| "next_href": "/memberships?page=2&page_size=2", | ||
| "last_href": "/memberships?page=14&page_size=2" | ||
| } | ||
| }, | ||
| "memberships": [{ | ||
| "id": "101", | ||
| "created_at": "2014-04-20T06:23:12Z", | ||
| "updated_at": "2014-04-20T06:23:12Z", | ||
| "state": "active", | ||
| "roles": ["group_admin"], | ||
| "links": { | ||
| "user": "12", | ||
| "user_groups": "31" | ||
| } | ||
| },{ | ||
| "id": "111", | ||
| "created_at": "2014-04-20T06:23:12Z", | ||
| "updated_at": "2014-04-20T06:23:12Z", | ||
| "state": "inactive", | ||
| "roles": [], | ||
| "links": { | ||
| "user": "12", | ||
| "user_groups": "20" | ||
| } | ||
| }] | ||
| } | ||
| ``` | ||
|
|
||
| ## Membership [/memberships/{id}] | ||
| A membership represents and user's status in a group and their role | ||
| within the group. | ||
|
|
||
| It has the following attributes: | ||
|
|
||
| - id | ||
| - created_at | ||
| - updated_at | ||
| - state | ||
| - roles | ||
| Attribute | Type | Description | ||
| --------- | ---- | ----------- | ||
| id | integer | read-only | ||
| created_at | string | read-only | ||
| updated_at | string | read-only | ||
| state | string | | ||
| roles | array(string) | | ||
|
|
||
|
|
||
| *id*, *created_at*, and *update_at* are assigned by the API. | ||
|
|
||
| Membership *state* can be "invited", "active", "inactive". When a user | ||
| is added to a group, their state is set to "invited". After they take | ||
| + Membership *state* can be: | ||
| + "invited" | ||
| + "active" | ||
| + "inactive" | ||
|
|
||
| When a user is added to a group, their state is set to "invited". After they take | ||
| action to join the group their state becomes "active". A User who leaves | ||
| a group has their state set to "inactive". | ||
|
|
||
| + Model | ||
|
|
||
| + Body | ||
|
|
||
| { | ||
| "links": { | ||
| "memberships.user_group": { | ||
| "href": "/user_groups/{memberships.user_group}", | ||
| "type": "user_groups" | ||
| }, | ||
| "memberships.user": { | ||
| "href": "/users/{memberships.user}", | ||
| "type": "users" | ||
| } | ||
| }, | ||
| "memberships": { | ||
| "id": "101", | ||
| "created_at": "2014-04-20T06:23:12Z", | ||
| "updated_at": "2014-04-20T06:23:12Z", | ||
| "state": "active", | ||
| "roles": ["group_admin"], | ||
| "links": { | ||
| "user": "12", | ||
| "user_groups": "31" | ||
| } | ||
| } | ||
| } | ||
|
|
||
| ### Retreive a Membership [GET] | ||
|
|
||
| + Request | ||
|
|
||
| + Headers | ||
|
|
||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
|
|
||
| + Response 200 | ||
|
|
||
| [Membership][] | ||
|
|
||
| ### Edit a Membership [PUT] | ||
| A user can ordinary only change their membership state. A user with | ||
| user group edit permissions can change the membership's roles. | ||
|
|
||
| + Request | ||
|
|
||
| + Headers | ||
|
|
||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
|
|
||
| + Body | ||
|
|
||
| { | ||
| "memberships": { | ||
| "state": "inactive" | ||
| } | ||
| } | ||
|
|
||
| + Response 200 | ||
|
|
||
| [Membership][] | ||
| ## List All Memberships | ||
| ```http | ||
| GET /api/memberships HTTP/1.1 | ||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| ``` | ||
|
|
||
| ### Destroy a Membership [DELETE] | ||
| Destroying a membership only sets the state to inactive. A user may | ||
| destroy their own memberships and a user with edit permission in a | ||
| user group may destroy membership for that group. | ||
|
|
||
| + Response 204 | ||
|
|
||
| ## Membership Collection [/memberships{?page,page_size,sort,user_id,user_group_id}] | ||
| A collection of Membership resources. | ||
|
|
||
| All collections add a meta attribute hash containing paging | ||
| information. | ||
|
|
||
| Memberships are returned as an array under *memberships*. | ||
|
|
||
| + Model | ||
|
|
||
| + Body | ||
|
|
||
| { | ||
| "links": { | ||
| "memberships.user_group": { | ||
| "href": "/user_groups/{memberships.user_group}", | ||
| "type": "user_groups" | ||
| }, | ||
| "memberships.user": { | ||
| "href": "/users/{memberships.user}", | ||
| "type": "users" | ||
| } | ||
| }, | ||
| "meta": { | ||
| "memberships": { | ||
| "page": 1, | ||
| "page_size": 2, | ||
| "count": 28, | ||
| "include": [], | ||
| "page_count": 14, | ||
| "previous_page": 14, | ||
| "next_page": 2, | ||
| "first_href": "/memberships?page_size=2", | ||
| "previous_href": "/memberships?page=14page_size=2", | ||
| "next_href": "/memberships?page=2&page_size=2", | ||
| "last_href": "/memberships?page=14&page_size=2" | ||
| } | ||
| }, | ||
| "memberships": [{ | ||
| "id": "101", | ||
| "created_at": "2014-04-20T06:23:12Z", | ||
| "updated_at": "2014-04-20T06:23:12Z", | ||
| "state": "active", | ||
| "roles": ["group_admin"], | ||
| "links": { | ||
| "user": "12", | ||
| "user_groups": "31" | ||
| } | ||
| },{ | ||
| "id": "111", | ||
| "created_at": "2014-04-20T06:23:12Z", | ||
| "updated_at": "2014-04-20T06:23:12Z", | ||
| "state": "inactive", | ||
| "roles": [], | ||
| "links": { | ||
| "user": "12", | ||
| "user_groups": "20" | ||
| } | ||
| }] | ||
| } | ||
|
|
||
| ### List all memberships [GET] | ||
| + Parameters | ||
| + page (optional, integer) ... index of the page to retrieve 1 by default | ||
| + page_size (optional, integer) ... number of items per page 20 by default | ||
| + sort (optional, string) ... field to sort by, id by default | ||
| + user_id (optional, integer) ... filter list to memberships for a user | ||
| + user_group_id (optional, integer) ... filter list to memberships for a user group | ||
|
|
||
| + Request | ||
|
|
||
| + Headers | ||
| All memberships add a meta attribute hash containing paging | ||
| information. | ||
|
|
||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| Memberships are returned as an array under *memberships*. | ||
|
|
||
| + Response 200 | ||
|
|
||
| [Membership Collection][] | ||
| ## Retreive a Membership | ||
| ```http | ||
| GET /api/memberships/123 HTTP/1.1 | ||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| ``` | ||
|
|
||
| ### Create a Membership [POST] | ||
| + Parameters | ||
| + id (required, integer) ... integer id of the resource to retrieve | ||
|
|
||
| ## Create a Membership | ||
| ```http | ||
| POST /api/memberships HTTP/1.1 | ||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| { | ||
| "memberships": { | ||
| "join_token": "decafbad", | ||
| "links": { | ||
| "user": "10", | ||
| "user_group": "11 | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| A membership creation request must include a link to a user and to a | ||
| user_group, although currently the linked user must always be the current user. | ||
| The request must also include the secret join_token of the user_group as an attribute | ||
| of the membership (although this property is not persisted). | ||
|
|
||
| + Request | ||
|
|
||
| + Headers | ||
|
|
||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| ## Edit a Membership | ||
| ```http | ||
| PUT /api/memberships/123 HTTP/1.1 | ||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| + Body | ||
| { | ||
| "memberships": { | ||
| "state": "inactive" | ||
| } | ||
| } | ||
| ``` | ||
| A user can ordinary only change their membership state. A user with | ||
| user group edit permissions can change the membership's roles. | ||
|
|
||
| { | ||
| "memberships": { | ||
| "join_token": "decafbad", | ||
| "links": { | ||
| "user": "10", | ||
| "user_group": "11 | ||
| } | ||
| } | ||
| } | ||
|
|
||
| + Response 201 | ||
| ## Destroy a Membership | ||
| ```http | ||
| DELETE /api/memberships/123 HTTP/1.1 | ||
| Accept: application/vnd.api+json; version=1 | ||
| Content-Type: application/json | ||
| ``` | ||
| Destroying a membership only sets the state to inactive. A user may | ||
| destroy their own memberships and a user with edit permission in a | ||
| user group may destroy membership for that group. | ||
|
|
||
| [Membership][] |