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

The DocumentValidation property validated_by is defined as type string, but the API responds/can respond with null.

I'd suggest to add "nullable": true to the property.

Get all documents related to a person /v1/people/{person_id}/documents/

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

The requests results in a 500 Internal Server Error response. Requesting a person's details, contains a list of its documents.

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

{
  "created_at": "2022-12-27T13:09:31.443720",
  "id": "34a36028-dddc-477f-9676-ceb75089658a",
  "tenant_id": "b25eb48b-abbd-46c5-a1bc-146fab1a1f58",
  "external_identifier": "string",
  "documents": [
    {
      "created_at": "2022-12-27T13:33:50.098073",
      "id": "fe3c44b4-86c1-4cd7-9335-bd183b4f48d1",
      "external_identifier": "string",
      "validations": []
    }
  ]
}