0

I'm designing a REST API and one if its endpoints is a search. Because the search query contains Personally identifiable information (PII) as a parameter, the endpoint uses POST with the PII parameter in the request body instead of a GET.

So my question is - if the PII parameter is invalid, do I return a 404 or a 422 ?

Example of the API I'm designing - to get all comments by a user .

POST /comments
Request body
{
  email: "test-user@gmail.com"
}

Edit: Clarifying my usage of "invalid" : I mean an email id that doesn't exist in our database. I know invalid is not the right term here, "unrecognised" is a better term maybe.

Neeraj
  • 2,376
  • 2
  • 24
  • 41
  • _" Because the search query contains Personally identifiable information (PII) as a parameter, the endpoint uses POST with the PII parameter in the request body instead of a GET."_ - why are you doing that? There's no prohibition on PII being in query-string parameters as far as I'm aware-of, and POST bodies are just-as-likely to be logged as URIs - so if you're using POST for a query-type-request then your web-service is _not_ RESTful because you aren't conforming to HTTP's semantics... – Dai Jun 15 '23 at 19:17
  • 1
    @Dai there's no web standard that forbids putting them as GET parameters, but it _is_ considered a security best practice to avoid this. – Evert Jun 15 '23 at 19:18
  • _"if the PII parameter is invalid"_ - by "invalid" do you mean malformed? or a well-formed email address that simply doesn't match any records you have? or something else? – Dai Jun 15 '23 at 19:19
  • @Evert Where's the "security" aspect here? – Dai Jun 15 '23 at 19:19
  • Do not use the HTTP error codes as your only response. Debugging will be a total pain if you just return a 404 and nothing else. 422 is a WebDAV response and makes zero sense here. At least return a JSON body of some sort. – stdunbar Jun 15 '23 at 19:21
  • @stdunbar 422 is not just a WebDAV response and is perfectly valid for validation errors. – Evert Jun 15 '23 at 19:21
  • @Evert 400 should be used instead - recent HTTP RFCs throw shade on HTTP 422: https://stackoverflow.com/questions/16133923/400-vs-422-response-to-post-of-data – Dai Jun 15 '23 at 19:24
  • Perhaps @Evert - but these [round peg/square hole questions](https://softwareengineering.stackexchange.com/questions/374031/what-should-be-the-http-status-code-for-service-not-available-in-your-area-err) come up all the time. – stdunbar Jun 15 '23 at 19:24
  • 1
    @Dai Using 422 was always fine, but the _most recent_ HTTP revision specifically blesses 422 for validation purposes (and also slightly rewords the human readable string): https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content That's from 2022. Even if you before hesitated using status code that weren't in the core spec, they are now. – Evert Jun 15 '23 at 19:25
  • 2
    @Evert Thank you - actually - I had no idea about HTTP 9110 (very recent too... only last year?) - looks like I've got some reading to do... – Dai Jun 15 '23 at 19:28
  • Yeah! It's nice that it's still being clarified and evolved. 422 is a good example where there was enough use that it made sense to codify it in the core. Also some spicy conversations around GET request bodies are now more clear ;) – Evert Jun 15 '23 at 19:30
  • @Evert re: request-bodies: [I thought that's what `QUERY` was for](https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-02.html)? (which would match the OP's question too, I guess...) – Dai Jun 15 '23 at 19:31
  • @Dai yeah I think this is an _excellent_ use-case for QUERY =) – Evert Jun 15 '23 at 19:43

1 Answers1

2

If with invalid you mean: "This is not a valid email address / doesn't look like an email address", then I would return 422.

If the purpose of your API is to return a list of comments made by a user with a specific email address, and there were no comments made by that user, I would return an empty array and 200 OK, as an 'empty set' is not an invalid request.

If you want to strongly indicated: "this user does not exist on our system", you could also consider 409

Evert
  • 93,428
  • 18
  • 118
  • 189
  • ...I don't see how HTTP 409 Conflict relates to "this user doesn't exist" - HTTP 409 Conflict should be used in response to something like a failed data-mutation race-condition or similar. – Dai Jun 15 '23 at 19:26
  • @Dai there's different interpretations, but I wrote a more lengthy essay on it here: https://evertpot.com/http/409-confict I think it's appropriate for a purpose like this. But when in doubt 400 is always ok. – Evert Jun 15 '23 at 19:27