JSON-Format for an attribute rendered as combobox in the UI

1

I wonder how the following simple situation would be specified using json:api.

We have a person object with a bunch of attributes. One of this attributes is country in which the person is living. In the User Interface the attribute country is rendered as a combo-box to be able to choose from a list of countries.

Would it be specified like below, assuming the current person would live in Switzerland?

...
"relationships": {
    "country" : {
        "links": {
        "self": "/person/1/relationships/country",
        "related": "/person/1/country"
   },
   "data": { "type": "country", "id": "9" }
}
...
"included": [{
    "type": "country",
    "id": "9",
    "attributes": {
        "name": "Switzerland"
    },
    "links": {
        "self": "/countries/9"
    }
}
...

Questions:

  • Is there simpler approach to model this scenario?
  • In order to fill the combobox with the list of countries it would be nice if somewhere the linke “/countries” would be specified within the document? How can this be achieved?
2

That looks about right. As for “simpler”, there are some fields that you’ve included that aren’t strictly required, such as links.

The complete list of countries would typically be fetched in a separate request to /countries. If you really want them included in the same request, you’d need to reference them from the primary resource with a relationship such as possible-countries and then list them all in included (it’s pretty hard to recommend this approach though).

3

Thanks for your answer. As a newcomer with json:api I feel now saver because you confirmed that I understood the concept of the specification.

My idea was not to include the list of countries in the same response. What I like to achieve is to place the link to “/countries” somewhere in the response. So that the client knows where to fetch the list of all countries. Otherwise the client needs to know this link. So how would you achieve this?

4

Currently, JSON API specifically supports a limited subset of IANA link types.

Your example seems to me to be a good use case for requiring the collection link, as documented in RFC 6573 - The Item and Collection Link Relations

When included in a resource that represents a member of a collection,
the ‘collection’ link relation identifies a target resource that
represents a collection of which the context resource is a member.

In your example, this would appear as:

...
"relationships": {
    "country" : {
        "links": {
          "self": "/person/1/relationships/country",
          "related": "/person/1/country",
          "collection": "/countries"
   },
   "data": { "type": "country", "id": "9" }
}
...

I can’t guarantee that JSON API won’t reserve this link for a slightly different purpose in the future, but to me this seems like the most clean solution.

1 Like