Deleting a Note

The person no longer needs note 42. The client sends:

DELETE /notes/42 HTTP/1.1
Host: api.notes.example

The request has no body, because the path identifies the note to delete. The response is:

HTTP/1.1 204 No Content

A 204 tells the client that the request succeeded and that there is nothing to send back. Some APIs send back the representation of the deleted resource. If you choose that convention, the response should be 200 OK with a body that is the representation of the note before it was deleted.

After the delete

The list of notes should not include deleted notes.

Suppose the client tries to read the note after it is deleted. It sends:

GET /notes/42 HTTP/1.1
Host: api.notes.example

The API responds with 404 Not Found:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "There is no note with id 42."
}

A second DELETE /notes/42 also gets 404, because there is no note 42 to delete.

In this API, deletion is permanent. There is no recycle bin to recover deleted notes. An app that lets a person undo a delete would perform a soft delete, keeping the note and marking it as deleted. The API would need another request (or a different endpoint) to list deleted notes and to restore one. I leave that out of scope.