From a91954d81e1e9be68f51ab1ecff2e400ed2e62cf Mon Sep 17 00:00:00 2001 From: yuenmichelle1 Date: Wed, 27 Dec 2023 14:02:42 -0600 Subject: [PATCH] update memberships (remove subheader link on collections remove subj links) --- docs/source/includes/_collections.md | 4 +- docs/source/includes/_memberships.md | 288 +++++++++++---------------- 2 files changed, 123 insertions(+), 169 deletions(-) diff --git a/docs/source/includes/_collections.md b/docs/source/includes/_collections.md index c536ae19b..36d08a02e 100644 --- a/docs/source/includes/_collections.md +++ b/docs/source/includes/_collections.md @@ -152,9 +152,9 @@ A user is permitted to add subject if they are the collection owner or have edit permissions. -## Remove subject links [/collection/{id}/links/subjects/{link_ids}] +## Remove subject links ```http -DELETE /api/collections/123/links/subjects/1 HTTP/1.1 +DELETE /api/collections/123/links/subjects/1,2 HTTP/1.1 Accept: application/vnd.api+json; version=1 Content-Type: application/json ``` diff --git a/docs/source/includes/_memberships.md b/docs/source/includes/_memberships.md index 041964df7..7df785de3 100644 --- a/docs/source/includes/_memberships.md +++ b/docs/source/includes/_memberships.md @@ -1,158 +1,87 @@ -# 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 @@ -160,42 +89,67 @@ Memberships are returned as an array under *memberships*. + 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][]