0

I am building a REST API which creates a resource. The resource has only one attribute which is a rather long and unique string. I am planning to send this data to the API as JSON. I see two choices for modeling the data as JSON

  1. A primitive JSON String data type
  2. A JSON object with one String attribute.

Both the options work.

Which of these two options is preferred for this context? And why?

swish41ffl
  • 137
  • 1
  • 8

1 Answers1

2

Basic Answer for Returning

I would personally use option 2, which is: `A JSON object with one String attribute.'

Also, in terms of design: I prefer to return an object, that has a key/value. The key is also a name that provides context as to what has been returned.

Returning just a string, basically a "" or {""} lacks that context ( the name of the returned variable.

Debate: Are primitive Strings Json Objects?

There seems to be also some confusion as to if a String by itself is a valid JSON document.

This confusion and debate, are quite evident in the following posts where various technical specs are mentioned: Is a primitive type considered JSON?

The only thing for sure is that a JSON object with a key-value pair is definitely valid!

As to a string by itself.. I'm not sure ( requires more reading).

Update: Answer In terms of creating/updating an entity (Post/Put)

In the specific case above, relating to such a large string that "runs into a few kilobytes"... my feeling is that this would be included within the request body.

In the specific context of sending data, I would actually be comfortable with using either 1 or 2. Additionally, 1 seems more optimized ( if your frameworks support it), since the context about what the data is, is related to the rest API method.

However, if in the future you need to add one more parameter, you will have to use a JSON entity with more than one key.

Community
  • 1
  • 1
Menelaos
  • 23,508
  • 18
  • 90
  • 155
  • 1
    The JSON standard only allows arrays and objects to be at the top level. Great answer! – Evert Sep 10 '18 at 23:03
  • @Evert Thanks for clearing that up! I'm reading the discussion in that stackoverflow post and it's a bit of a mix ahhaha :D – Menelaos Sep 10 '18 at 23:06
  • I'm actually taking it back. I wanted to be sure, but it turns out that the RFC does indeed allow everything at the top-level: https://tools.ietf.org/html/rfc8259#section-2 – Evert Sep 10 '18 at 23:12
  • @Evert It's so annoying that they seem to have sort of changed their minds on that. – Menelaos Sep 10 '18 at 23:13
  • Yea! I just looked it up and it wasn't the case with RFC4627! – Evert Sep 10 '18 at 23:16
  • @Evert , reminds me of another question I had answered: https://stackoverflow.com/questions/16459954/understanding-the-additionalproperties-keyword-in-json-schema-draft-version-4/17339316#17339316 . They love driving us crazy!!!! – Menelaos Sep 10 '18 at 23:17
  • 1
    @MenelaosBakopoulos. Just wanted to clarify... I was referring to JSON data that is sent as input to the API. In this case the resource itself, I thought, will set the context as to what the data is about. For instance if the resource where to be an email (i.e. the API end point is /email) and the data is . PUT /email/ would make sense. But as I said since the data in my case is a string running into a few kilobytes I can't model it so. So, I was looking at alternative options – swish41ffl Sep 10 '18 at 23:21