0

For some rest resource, there are two fields connected. There is, if one field is POST/PUT it gets the value of the other field.

In this example we have a amount and amountWithVat(with tax or Value Added Tax). If you POST or PUT a null for amountWithVat the default value will be from amount.

Example 1
POST
amount=150
amountWithVAT=null
GET
amount=150
amountWithVAT=150

Example 2
POST
amount=150
amountWithVAT=170
GET
amount=150
amountWithVAT=170
PUT
amount=200
amountWithVAT=null
GET
amount=200
amountWithVAT=200

For me this does not feel intuitive, but from the view of a front end developer this could make sense. Personally I would rather enforce this by forbidding POST/PUT nulls.

Are there any guidelines or best practices which go against this?

  • Well this does raise some questions. Where is the default value here? What would have happened if you'd put a GET immediately after the POST in example 2? Why do the nulls only go in the Vat? What the hecks a Vat? I can't tell if it's the design or the examples that aren't intuitive. – candied_orange May 4 '17 at 20:00
  • @CandiedOrange I added the details you asked for in the question. So amountWithVat gets the default value of amount if omitted. Vat is Value Added Tax. – Jakob May 4 '17 at 20:38
  • Pro tip: capitalize abbreviations. Or your maintenance programmer will find you and dunk you in a vat of acid. – candied_orange May 4 '17 at 21:32
  • @CandiedOrange Even when they are longer then 2 characters? Is this a special rest convention I am not aware of? Typically in .net 3+ abbreviations are pascal. IO, Xml, Html etc... – Jakob May 4 '17 at 21:39
1

Depending on who plans to use the service I would say the guideline that this goes against is that it is not self documenting. If I were to

POST
amount=150

for the first time I would expect

GET
amount=150
amountVAT=null

Now if there is a requirement that says amountVAT can't be null, I think the best solution would be to notify the consumer

POST
amount=150
Response:
400: Bad Request
message: amountVAT can not be null / blank

That way the consumer is informed that amountVAT is required and can decide for themselves if they want to set it to the same as amount, or a different value.

  • And when the lawsuits start because someone couldn't tell if they are supposed add amount to amountVAT, or if the server adds them, your defense will be? – candied_orange May 4 '17 at 23:05
  • I'm not sure I understand the premise. If the users are required to define the value for amountVAT, but don't put the right value in, they made a mistake, yes? If they want logic that says 'amountVAT cannot be less then amount' then that would be a constraint to add. And we could return that message with Bad Request. I'm not sure what 'if they are supposed add amount to amountVAT' means. But I also don't know what amountVAT is, so I wouldn't know how it is derived. – Cole Ole May 4 '17 at 23:15
  • That's my point. You can't fix this with validation. You fix this with a better name then "amount". Self documenting, remember? – candied_orange May 4 '17 at 23:21

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.