0

I’m reviewing my colleague’s code. He created an endpoint for receiving the client’s feedback from a like/dislike button. He designed the API this way:

  • it is accessible at{{url}}/great_new_feature/feedback;
  • it accepts POST requests only ;
  • Request body should be strictly one of those (binary option): {"feedback": "Not Satisfied"} and {"feedback": "Satisfied"}

I find all of this overly complicated and redundent. So here’s my (two-parts) question:

  • Could we not have an endpoint that receives only a single string (like / dislike), without having it encapsulated in a JSON object ? Is it still a RESTful design? (This post suggests that a string is considered valid JSON)
  • Isn’t it a code smell to have a REST endpoint that receives only a single-field information (and, in this case, actually a binary one: true/false)? If so, how should I correct that?
kotchwane
  • 2,082
  • 1
  • 19
  • 24
  • Admittedly, any question about design, architecture, clean code, or optimal use of resources, can be seen as opinion-based. Should they all disappear from this site, though ? They are the essence of a developer’s day-to-day job, and they can be compared to objective criteria - performance, generally accepted standards, popularity... – kotchwane Mar 01 '22 at 09:47

1 Answers1

1

Could we not have an endpoint that receives only a single string (like / dislike), without having it encapsulated in a JSON object ? Is it still a RESTful design? (This post suggests that a string is considered valid JSON)

Yes, you can. There is no rule that says that a request payload must be an object, or even that a request payload must be JSON. On the web, many request payloads are application/x-www-form-urlencoded key value pairs.

The trade off is that you can extend the schema of an object by adding more "optional" fields, without breaking backwards compatibility.

Isn’t it a code smell to have a REST endpoint that receives only a single-field information (and, in this case, actually a binary one: true/false)?

Yes - in the sense that a "smell" indicates that there might be a problem somewhere (see https://wiki.c2.com/?CodeSmell ).

There's nothing wrong with having a document that has but a single field of information in it.

Similarly, there's nothing wrong with making such a document available via the web; there's nothing wrong with supporting changes to that document from the web.

Things get a little bit suspicious when you send edits to one resource expecting the effects to show up somewhere else. For example, if we are submitting

POST /api/great_new_feature/feedback

In the expectation that it will change what we see when we

GET /api/great_new_feature

Then that deserves further review, because it impedes the general purpose cache invalidation mechanism built into HTTP. If you are giving up something that is "free", then you better be sure that you are being compensated. In a code review, I would expect to find a decision record documenting the investigation and its findings.

I’m not sure I understand the last paragraph about cache invalidation. Is it specific to an API expecting a single field of information ? 

No. HTTP message semantics are part of its uniform interface -- all resources understand messages the same way.

And what is a generally accepted solution to this problem? (I see that the whole website I work on has a Cache-Control: no-store policy)

Ensure that requests that modify information use the same target URI as the requests that read information.

POST /collection

Is a popular choice for introducing new items into a collection because (in part) we expect that the introduction of the new item also changes the representation of the collection itself (typically with a link to the new item).

VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • Thank you for your answer. I’m not sure I understand the last paragraph about cache invalidation. Is it specific to an API expecting a single field of information ? It seems to apply to any `POST` request. And what is a generally accepted solution to this problem? (I see that the whole website I work on has a `Cache-Control: no-store` policy) – kotchwane Mar 01 '22 at 09:51