[API] DELETE endpoints respond differently

[AndreSchwarzer]

The Issue I encountered

When deleting resources I expect the same/similar responses from the API.

• Deleting an existing person results currently in a 200 response with a JSON body.
• Deleting an non existing person results currently in a 404 response with a JSON body.
• Deleting an existing document results currently in a 200 response with a text body.
• Deleting an non existing document results currently in a 200 response with a text body.

I would expect a 204 No Content for a successful deletion and a 404 Not Found, maybe with further details in a JSON body, as a response.

In case 200 OK is the desired status for this project, the response should, in IMHO, be always a JSON in the same schema.

How to reproduce the description above

Delete a person by id /v1/delete_person

Resource exists

Call

curl -X 'DELETE' \
  'https://sandbox.api.credentials.dev/v1/people/34a36028-dddc-477f-9676-ceb75089658a/' \
  -H 'accept: application/json' \
  -H 'X-API-Key: REDACTED'

Response

Code: 200 Body:

{
  "deleted": true
}

Resource doesn't exists (anymore)

Call

curl -X 'DELETE' \
  'https://sandbox.api.credentials.dev/v1/people/34a36028-dddc-477f-9676-ceb75089658a/' \
  -H 'accept: application/json' \
  -H 'X-API-Key: REDACTED'

Response

Code: 404 Body:

{
  "detail": "Could not find this person for this tenant."
}

Delete a document by id /v1/people/{person_id}/documents/{document_id}/

Resource exists

Call

curl -X 'DELETE' \
  'https://sandbox.api.credentials.dev/v1/people/34a36028-dddc-477f-9676-ceb75089658a/documents/c2141f12-8d69-47d1-8ea5-779496a8ac53/' \
  -H 'accept: application/json' \
  -H 'X-API-Key: REDACTED'

Response

Code: 200 Body:

true

Resource doesn't exists (anymore)

Call

curl -X 'DELETE' \
  'https://sandbox.api.credentials.dev/v1/people/34a36028-dddc-477f-9676-ceb75089658a/documents/c2141f12-8d69-47d1-8ea5-779496a8ac53/' \
  -H 'accept: application/json' \
  -H 'X-API-Key: REDACTED'

Response

Code: 200 Body:

false

[AndreSchwarzer]

My suggestion would be to use a Schema like this for example to represent the deletion status, in case the "200 OK" solution is picked. The schema is based on the current successful deletion of a person resource.

"DeletionStatus": {
	"title": "DeletionStatus",
	"type": "object",
	"properties": {
		"deleted": {
			"title": "Deleted",
			"type": "boolean"
		}
	}
}

[LilithWittmann]

Implemented in ccf976.

[AndreSchwarzer]

Just to verify, since the current active version is 107ed6d and I can't verify if its newer or older than ccf976:

Case 1 and 2 is what I've to expect to receive from the API, correct?

case 1: "Resource exists"

• Request deletion
  • if deleted: 200 with { "deleted": true }
  • unable to delete: 200 with { "deleted": false }
    • Resource still exists and wasn't yet deleted, for whatever reason

case 2: "Resource doesn't exist"

• Request deletion
• 404 with details such as {"detail":"Could not find this person for this tenant."}

further issue

The document deletion request for document ID a3e6854b-f55c-4e2e-baac-9ceb27587298 of person 7f89089b-d7a2-47a3-9cd4-e4c0c89c02d0 seems to result always in a DeletionStatus response with a content of { "deleted": false }.

Is there a reason why this document can't be deleted (by me)?

curl -X 'DELETE' \
  'https://sandbox.api.credentials.dev/v1/people/7f89089b-d7a2-47a3-9cd4-e4c0c89c02d0/documents/a3e6854b-f55c-4e2e-baac-9ceb27587298/' \
  -H 'accept: application/json' \
  -H 'X-API-Key: REDACTED'