CODEWITHSUNDEEP
apiresthttp-headers
klotz
klotz

Reputation: 2041

Add instruction 'how' to perform a REST API request by adding header or body param?

Imagine a simple REST API that allows to create a user account, by sending a JSON resource to POST /users as in the following. By default it sends out a confirmation email to the user.

{
   "username": "[email protected]",
   "password": "secret"
}

However sometimes there are good reasons for not sending out a confirmation based on the use case, e.g. another API client, or admins signing up users on their behalf.

Since it doesn't have any implications on the created resource but is more of an instruction how to create the user, should it be separate from the request body? What's the best way to do this?

  1. Specify a custom header Confirmation: no-confirmation
  2. Add a query param ?confirmation=false
  3. Add a send_confirmation field to the request body

Upvotes: 0

Views: 333

Answers (1)

Robert Bräutigam
Robert Bräutigam

Reputation: 7744

Let's take the options in order:

  1. Adding a header value to indicate some semantic difference should be generally avoided. The API should be "browseable", meaning it should be discoverable following links only.

  2. Adding a query parameter is, from REST perspective completely equal to creating another URI. It does not really matter how you expose it, the point is that the client needs to follow some links from the previous "state" it was in. This is actually ok, as long as the links to these resources indicate the different semantics you described: like creating users by admin, users creating themselves, etc.

    Also note, that the API should not necessarily expose whether a confirmation is sent. The API should expose the "purpose", the server then can decide whether the use-case warrants a confirmation email.

  3. Putting a send_confirmation in the JSON representation itself. This is ok, if this is a functionality available for the user. For example I can ask for a confirmation email. If I can't, and it is only used for differentiating different use-cases, then I would rather prefer option 2.

Summary: For the case you are describing I would pick option 2: different resources for admins and normal users.

Upvotes: 1

Related Questions