Skip to content

Commit

Permalink
DEV-27677 I can delete users in bulk (#87)
Browse files Browse the repository at this point in the history 
* docs: add bulk delete API documentation

* style: adjust indentation

* style: adjust result indentation

* docs: update result description

* docs: cleanup documentation

* docs: remove location field with null values

* style: indentation adjustment

* docs: lowercase for starting comments

* docs: add documentation for bulk delete unknown/invalid user ids

* docs: update null as bad request

* docs: apply review suggestions

* docs: add sample request with errors in response

* docs: update description for API request

* docs: moved comment to description section

* docs: rename delete to deleted

* docs: update sentence for request of users that cannot be deleted

Co-authored-by: Patrick Nyakoria <patrick.nyakoria@acrolinx.com>
Co-authored-by: George Haddad <george-haddad@users.noreply.github.com>
  • Loading branch information
@mrnyax @george-haddad
3 people committed Nov 10, 2021
1 parent 293c0b4 commit 4afe165
Showing 1 changed file with 267 additions and 7 deletions.
274 changes: 267 additions & 7 deletions apiary.apib
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3403,11 +3403,11 @@ This method uses the *id* to release an active license consumed by a user.

### Request User Information Update [PUT /api/v1/user/{id}/_request_cf_update]

The user specified by the *id* in this request will be asked to update their user information.
The user specified by the *id* in this request will be asked to update their user information.

**Note:**
- The next time the user signs in, they'll need to re-enter their user information via a form.
- If you repeat the request for the same user UUID, you won't be notified that a request was already submitted.
- If you repeat the request for the same user UUID, you won't be notified that a request was already submitted.
- To do this, you need the `UserAndRoles.editUser` privilege.

+ Parameters
Expand Down Expand Up @@ -3826,7 +3826,7 @@ noted in the Create User API section.
### Request User Information Update in Bulk [PUT /api/v1/user/bulk/_request_cf_update]

This API is the bulk operation for "Request User Information Update" from the "User Commands" group.
It lets you ask multiple users to update their user information.
It lets you ask multiple users to update their user information.

**Note:** There are currently no limitations on the number of users a client can ask for an information update.

Expand All @@ -3837,15 +3837,15 @@ It lets you ask multiple users to update their user information.
X-Acrolinx-Auth: your_access_token

+ Attributes (object)

+ Body

[
"1f17395a-770f-439e-b2b4-65c6c03717db",
"2f17395a-770f-439e-b2b4-65c6c03717db",
"3f17395a-770f-439e-b2b4-65c6c03717db",
]

+ Response 207 (application/json)

+ Attributes (BulkResultResponse)
Expand Down Expand Up @@ -3904,15 +3904,15 @@ It lets you ask multiple users to update their user information.
X-Acrolinx-Auth: your_access_token

+ Attributes (object)

+ Body

[
"f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f",
"no-user-with-this-id-for-sure",
null
]

+ Response 207 (application/json)

+ Attributes (BulkResultResponse)
Expand Down Expand Up @@ -3973,6 +3973,266 @@ It lets you ask multiple users to update their user information.
}
}

### Delete Users in Bulk [DELETE /api/v1/user/bulk]

This API lets you delete a list of users. All user ids follow the requirements and constraints
noted in the "Delete User API" section.

**Note:** You can delete up to 100 users per bulk request, the minimum is 1.

+ Request Delete users in bulk (application/json)

This request lets you delete 5 users by specifying user UUIDs in the request object.

Example when all users were successfully deleted

+ Headers

X-Acrolinx-Auth: your_access_token

+ Body

[
"d6601a5b-c74e-4753-8d7a-4a7d15e71149",
"d7b6d898-79b2-4a8b-9afd-760fdda9c921",
"bb284474-e107-413e-9c15-d813ed7209e9",
"c4eba54b-4cb6-4045-85f1-88e72fd9be6f",
"b08309c7-87ee-4270-8d94-de5a916d24be"
]

+ Response 207 (application/json)

+ Attributes (BulkResultResponse)

+ Body

{
"results": [
{
"status": 204,
"id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149"
},
{
"status": 204,
"id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921"
},
{
"status": 204,
"id": "bb284474-e107-413e-9c15-d813ed7209e9"
},
{
"status": 204,
"id": "c4eba54b-4cb6-4045-85f1-88e72fd9be6f"
},
{
"status": 204,
"id": "b08309c7-87ee-4270-8d94-de5a916d24be"
}
],
"errors": []
}

+ Request Example with users that can't be deleted (application/json)

+ Headers

X-Acrolinx-Auth: your_access_token

+ Attributes (object)

+ Body

[
"d6601a5b-c74e-4753-8d7a-4a7d15e71149",
"d7b6d898-79b2-4a8b-9afd-760fdda9c921",
"bb284474-e107-413e-9c15-d813ed7209e9",
"c4eba54b-4cb6-4045-85f1-88e72fd9be6f",
"b08309c7-87ee-4270-8d94-de5a916d24be"
]

+ Response 207 (application/json)

+ Attributes (BulkResultResponse)

+ Body

{
"results": [
{
"status": 204,
"id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149"
},
{
"status": 204,
"id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921"
}
],
"errors": [
{
"status": 409,
"id": "b08309c7-87ee-4270-8d94-de5a916d24be",
"type": "client",
"title": "Conflict",
"detail": "Cannot delete own account",
"reference": "06bc308c-c65d-45eb-a626-a9cc5908798c"
},
{
"status": 409,
"id": "d6601a5b-c74e-4753-8d7a-4a7d15e71149",
"type": "client",
"title": "Conflict",
"detail": "Built-in user \"admin (admin) \" cannot be deleted",
"reference": "b08309c7-87ee-4270-8d94-de5a916d24be"
},
{
"status": 404,
"id": "d7b6d898-79b2-4a8b-9afd-760fdda9c921",
"type": "client",
"title": "Not Found",
"detail": "An unspecific client error occurred.",
"reference": "c0c67650-4fd6-42a4-9300-1f9431274912"
}
]
}

+ Response 400 (application/json)

// when a bulk delete request is sent with an empty list
{
"links": {},
"error": {
"reference": "ea0ef815-435b-4311-8937-c32ece0c7cc4",
"detail": "Check the request for invalid values or missing parameters.",
"type": "validation",
"title": "Invalid request attributes",
"validationDetails": [
{
"title": "Validation error",
"constraint": "Size",
"detail": "size must be between 1 and 100",
"invalidValue": "[]"
}
],
"status": 400
}
}

// when a bulk delete request exceeds the maximum valid limit
{
"links": {},
"error": {
"reference": "a2616dcb-1009-47c6-a6cd-34fe71776dd5",
"detail": "Check the request for invalid values or missing parameters.",
"type": "validation",
"title": "Invalid request attributes",
"validationDetails": [
{
"title": "Validation error",
"constraint": "Size",
"detail": "size must be between 1 and 100",
"invalidValue": "[d6601a5b-c74e-4753-8d7a-4a7d15e71149, d7b6d898-79b2-4a8b-9afd-760fdda9c921, ...]"
}
],
"status": 400
}
}

// when a bulk request is sent without a payload body
{
"links": {},
"error": {
"reference": "f36cbe4d-0ebb-44c1-9771-2555cb17f025",
"detail": "Check the request for invalid values or missing parameters.",
"type": "validation",
"title": "Invalid request attributes",
"validationDetails": [
{
"title": "Validation error",
"constraint": "NotNull",
"detail": "must not be null",
"invalidValue": null
}
],
"status": 400
}
}

+ Request Example with invalid or unknown user ids in request (application/json)

+ Headers

X-Acrolinx-Auth: your_access_token

+ Attributes (object)

+ Body

[
"f265a1b7-4fed-4ff3-b2d4-9dc6e29e268f",
"no-user-with-this-id-for-sure",
null
]

+ Response 207 (application/json)

+ Attributes (BulkResultResponse)

+ Body

{
"results": [
{
"status": 204,
"id": "33b5b2e3-6870-4ecb-92f9-ac496a9ac2c3"
}
],
"errors": [
{
"status": 404,
"id": "no-user-with-this-id-for-sure",
"type": "client",
"title": "Not Found",
"detail": "HTTP 404 Not Found",
"reference": "8aafe860-8fa7-4f5f-89c6-40dda1c444c4"
},
{
"status": 400,
"id": null,
"type": "client",
"title": "Bad Request",
"detail": "The provided uuid is not a valid user id.",
"reference": "cc3c4907-5fa2-40e9-988a-3623a5c358d7"
}
]
}

+ Response 403 (application/json)

// when you don’t have the privilege to delete users
{
"links": {},
"error": {
"detail": "The user does not have the required privileges to perform the operation.",
"type": "insufficientPrivileges",
"title": "Insufficient privileges",
"status": 403
}
}

+ Response 500 (application/json)

// when there’s an unspecified error
{
"links": {},
"error": {
"reference": "2f17395a-770f-439e-b2b4-65c6c03717db",
"detail": "An unspecific server error occurred. Details may be found in the Acrolinx log files.",
"type": "server",
"title": "Unspecific server error",
"status": 500
}
}

# Group Licenses API

License information is provided by the following set of APIs.
Expand Down

0 comments on commit 4afe165

Please sign in to comment.