Update docs with recent changes to membership APIs #9210
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -102,7 +102,7 @@ info: | |
| | 500 | Server Error | An error occurred with our API | | ||
|
|
||
| servers: | ||
| - url: https://hypothes.is/api | ||
|
|
||
| # ----------------------------------------------------------------------------- | ||
| # Reusable tags for grouping operations | ||
|
|
@@ -111,6 +111,7 @@ tags: | |
| - name: general | ||
| - name: annotations | ||
| - name: groups | ||
| - name: memberships | ||
|
There was a problem hiding this comment. The membership APIs used to be listed under groups in the docs. I'm moving them out into their own separate section since they do form a separate set of endpoints (list-memberships, add-membership, get-membership, edit-membership and delete-membership). Like annotation, user and group, "membership" is now a first-class noun in the h model and API. |
||
| - name: profile | ||
| - name: users | ||
|
|
||
|
|
@@ -122,6 +123,25 @@ components: | |
| # Reusable parameters | ||
| # ------------------------- | ||
| parameters: | ||
| PageNumber: | ||
| name: "page[number]" | ||
| in: query | ||
| required: false | ||
| description: Which page of results to get | ||
| schema: | ||
| type: int | ||
| default: 1 | ||
| minimum: 1 | ||
| PageSize: | ||
| name: "page[size]" | ||
| in: query | ||
| required: false | ||
| description: How many items to get per page | ||
| schema: | ||
| type: int | ||
| default: 20 | ||
| minimum: 1 | ||
| maximum: 100 | ||
|
Comment on lines
+126
to
+144
There was a problem hiding this comment. Putting the pagination query params in a reusable place. They're currently only used by one endpoint but if we ever add another endpoint with page-based pagination we'll want to re-use the same query params. That said I don't know if/how you can customize the There was a problem hiding this comment.
You can use |
||
| AnnotationID: | ||
| name: id | ||
| in: path | ||
|
|
@@ -265,6 +285,12 @@ components: | |
| $ref: './schemas/user-new.yaml#/User' | ||
| UserUpdate: | ||
| $ref: './schemas/user-update.yaml#/User' | ||
| Membership: | ||
| $ref: './schemas/membership.yaml#/Membership' | ||
| MembershipCreate: | ||
| $ref: './schemas/membership-create.yaml#/Membership' | ||
| PaginationMeta: | ||
| $ref: './schemas/pagination-meta.yaml#/PaginationMeta' | ||
|
Comment on lines
+288
to
+293
There was a problem hiding this comment. Reusable schemas for various parts of membership API request and response bodies. |
||
|
|
||
| # ----------------------------------------------------------------------------- | ||
| # API OPERATIONS | ||
|
|
@@ -851,76 +877,135 @@ paths: | |
| # --------------------------------------------------------------------------- | ||
|
|
||
| # --------------------------------------------------------------------------- | ||
| # GET groups/{id}/members - Get group memberships | ||
| # --------------------------------------------------------------------------- | ||
| /groups/{id}/members: | ||
| get: | ||
| tags: | ||
| - memberships | ||
| summary: Get group memberships | ||
| description: | | ||
| Get a paginated list of all user memberships in a group. | ||
| To get the memberships of a private group the authenticated user must be a member of the group. | ||
| Getting the memberships of an open or restricted group does not require authentication. | ||
| The returned memberships are sorted by joining date, oldest first. | ||
|
|
||
| If the `page[number]` query param is included in the request then the response will be paginated. | ||
| If there's no `page[number]` query param in the request then a legacy, | ||
| un-paginated response format will be used. In the future this legacy | ||
| un-paginated response format will be removed and the paginated response | ||
| format will be used even when the `page[number]` query param is not | ||
| present. | ||
|
Comment on lines
+893
to
+898
There was a problem hiding this comment. There's a PR ready to remove the un-paginated API when we're ready to do that, and I've included removing this stuff from the docs: #9183 |
||
| parameters: | ||
| - $ref: '#/components/parameters/PageNumber' | ||
| - $ref: '#/components/parameters/PageSize' | ||
| security: | ||
| - AuthClient: [] | ||
| - ApiKey: [] | ||
| - {} | ||
| responses: | ||
| '200': | ||
| description: Success | ||
| content: | ||
| application/*json: | ||
| schema: | ||
| oneOf: | ||
| - title: "Paginated" | ||
| type: object | ||
| properties: | ||
| meta: | ||
| description: "Metadata about this response." | ||
| type: object | ||
| properties: | ||
| page: | ||
| $ref: '#/components/schemas/PaginationMeta' | ||
| data: | ||
| description: "The list of memberships for the requested page." | ||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/Membership' | ||
| - title: "Unpaginated (deprecated)" | ||
|
There was a problem hiding this comment. If this is deprecated, I reckon you can also add There was a problem hiding this comment. I actually did try this but it didn't seem to do anything |
||
| type: array | ||
| items: | ||
| $ref: '#/components/schemas/Membership' | ||
|
|
||
| /groups/{id}/members/{user}: | ||
| # ---------------------------------------------------------- | ||
| # POST groups/{id}/members/{user} - Add user to group | ||
| # ---------------------------------------------------------- | ||
| post: | ||
| tags: | ||
| - memberships | ||
| summary: Add member to group | ||
| description: | | ||
| Add a user as a member to a group. | ||
| security: | ||
| - AuthClient: [] | ||
| parameters: | ||
| - $ref: '#/components/parameters/GroupID' | ||
| - $ref: '#/components/parameters/UserID' | ||
| requestBody: | ||
| required: false | ||
| content: | ||
| application/*json: | ||
| schema: | ||
| $ref: '#/components/schemas/MembershipCreate' | ||
| responses: | ||
| '200': | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Membership' | ||
|
|
||
| # ------------------------------------------------------------------------ | ||
| # PATCH groups/{id}/members/{user} - Change a user's membership in a group | ||
| # ------------------------------------------------------------------------ | ||
| patch: | ||
| tags: | ||
| - memberships | ||
| summary: Update membership | ||
| description: | | ||
| Update a user's membership in a group. | ||
|
|
||
| To update *your own* membership you can use the alias `me` in place of `{user}`. | ||
| This is equivalent to using your own user ID. | ||
| security: | ||
| - ApiKey: [] | ||
| parameters: | ||
| - $ref: '#/components/parameters/GroupID' | ||
| - $ref: '#/components/parameters/UserID' | ||
| requestBody: | ||
| required: true | ||
| content: | ||
| application/*json: | ||
| schema: | ||
| $ref: '#/components/schemas/MembershipCreate' | ||
| responses: | ||
| '200': | ||
| description: Success | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: '#/components/schemas/Membership' | ||
|
|
||
| # ---------------------------------------------------------- | ||
| # DELETE groups/{id}/members/{user} - Remove user from group | ||
| # ---------------------------------------------------------- | ||
| delete: | ||
| tags: | ||
| - memberships | ||
| summary: Remove member from group | ||
| description: | | ||
| Remove a user from a group. | ||
|
|
||
| To remove *yourself* from a group you can use the alias `me` in place of `{user}`. | ||
| This is equivalent to using your own user ID. | ||
| security: | ||
| - ApiKey: [] | ||
| parameters: | ||
| - $ref: '#/components/parameters/GroupID' | ||
| - $ref: '#/components/parameters/UserID' | ||
| responses: | ||
| '204': | ||
| $ref: '#/components/responses/NoContent' | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thought I'd fix this while I was here: all the example URLs in our docs have been wrong, presumably since we first moved to redoc.