-1

I'm learning REST and I have a question.

Is there a scenario where the endpoint person/pathParm1/PathParam2 is legitimate?

For example:

person/ben/stiller
people /2/4

As far as I understand REST, query parameters should be used for searches:

person?firstName=ben&secondName=stiller

or

person/2/order4
jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
TheAnonymousModeIT
  • 777
  • 1
  • 6
  • 18
  • more info on this can be found here: [REST API Best practices: Where to put parameters?](https://stackoverflow.com/questions/4024271/rest-api-best-practices-where-to-put-parameters). If something is valid syntax, or legitimate, is determined by the application which receives the request (because that should throw an error, when the question is incorrect) – Luuk Dec 31 '22 at 12:58

1 Answers1

0

REST doesn't care what spelling conventions you use for your resource identifiers.

So if you want to have a URI template with multiple variables to expand, and more than one of those variables are expanded as path segments, that's fine.

For example, you'll notice that your browser has no trouble with this resource identifier:

https://stackoverflow.com/questions/74969638/endpoint-with-two-path-parameters

which might reasonably be produced by expanding variables into a template like

https://stackoverflow.com/questions/{id}/{hint}

As far as I understand REST, query parameters should be used for searches:

That's not a REST constraint, although for the special case of the web it turned out that way. This is primarily a historical accident: we didn't have standards for URI templates when the web was young, which meant that searches came about from the standardized implementation of HTML form submissions (application/x-www-form-urlencoded key value parameters replacing the query part of the form action)

REST does say that we use resource identifiers to... identify resources; and that we all use the same general purpose resources (ie: conforming to the production rules defined in RFC 3986), but without constraints on the spelling or semantics of those identifiers.

Example: URL shorteners work.

(Note: your misunderstanding is a common one, and not at all your fault; the literature sucks. FWIW, I was once where you are; Stefan Tilkov's 2014 talk was the one that really got my own thinking straightened out.)

That said, you might find a "query parameters should be used for searches" constraint coming from somewhere else; a local style guide, for example.

this means I could also make a restful endpoint like this: api/person/{firstName}/{lastName} instead api/person?firstName=ben&lastName=stiller ?

Yes; you can use either of those spellings for your resource identifiers, and all of the general purpose components out there will still "just work" -- because they are treating the resource identifier as semantically opaque.

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • ok, so this means I could also make a restful endpoint like this: api/person/{firstName}/{lastName} instead api/person?firstName=ben&lastName=stiller ? – TheAnonymousModeIT Jan 01 '23 at 07:04
  • What's the purpose of the second path parameter in https://stackoverflow.com/questions/74969638/endpoint-with-two-path-parameters? The following endpoint also works https://stackoverflow.com/questions/74969638 so the second parameter is not really necessary – TheAnonymousModeIT Jan 01 '23 at 07:07
  • I suspect that the second path parameter is used for no other reason than to help human beings who are, for example, looking at a the URI in a browser history, to recall which identifier goes with which web page. – VoiceOfUnreason Jan 01 '23 at 12:10
  • ok I see. Thank you. And regarding the api design: I could also make a restful endpoint like this: api/person/{firstName}/{lastName} instead api/person?firstName=ben&lastName=stiller ? – TheAnonymousModeIT Jan 02 '23 at 06:21
  • Yes - you might prefer the latter if you are expecting to use HTML forms as your "URI template"; you might prefer the former if you are going to be using relative references to link to other resources in the same hierarchy. Notice that these are purely mechanical concerns; they have nothing to do with the meaning of the sub parts of your identifiers. – VoiceOfUnreason Jan 02 '23 at 06:31