[PLAT-931] Add External Identities endpoints to docs #25
Conversation
swagger-spec/swagger.yaml
Outdated
| @@ -1253,6 +1253,12 @@ paths: | |||
| /users/{user_id}/: | |||
| $ref: 'users/detail.yaml' | |||
|
|
|||
| /users/{user_id}/identities/: | |||
There was a problem hiding this comment.
From the OSF PR, it looks like this URL is /users/{uid}/settings/identities/
| '200': | ||
| description: 'OK' | ||
| schema: | ||
| $ref: definition.yaml |
There was a problem hiding this comment.
This should reference an external identity definition. Currently the response schema implies that a fully serialized user is returned, when it's just the external identity.
vs.
| id: q7fts | ||
|
|
||
| delete: | ||
| summary: Delete user's external identities |
There was a problem hiding this comment.
For consistency, would suggest "Remove an external identity"
| @@ -0,0 +1,96 @@ | |||
| get: | |||
| summary: Retrieve user's external identities | |||
There was a problem hiding this comment.
For consistency, would suggest "Retrieve an external identity"
| @@ -0,0 +1,43 @@ | |||
| get: | |||
| summary: List all user's external identities | |||
There was a problem hiding this comment.
For consistency, would suggest "List all external identities" (the summary for listing user preprints, for example, is "List all preprints")
| - Users | ||
| operationId: external_identities_detail | ||
| responses: | ||
| '200': |
There was a problem hiding this comment.
Does this return 200? Shouldn't a delete request return 204 No Content?
|
|
||
| The returns deleted information including the external identity's name, status and id. | ||
|
|
||
| #### Returns |
There was a problem hiding this comment.
See other delete request sections, I think this should be:
#### Returns
If the request is successful, no content is returned.
If the request is unsuccessful, a JSON object with an errors key containing information about the failure will be returned. Refer to the [list of error codes](#tag/Errors-and-Error-Codes) to understand why this request may have failed.
There was a problem hiding this comment.
Like other sections, please add a "Permissions" section to explain that users can only delete their own identities.
Purpose
We have CenterForOpenScience/osf.io#8540, so we need to document it!
Changes
Ticket
https://openscience.atlassian.net/projects/PLAT/issues/PLAT-931