Should [ ] be escaped in response links?

1

Should the query params in links appearing in JSON-API responses be percent-encoded?

The examples from jsonapi.org are not encoded, as in:

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    }
  ]
}

However, there is also a note regarding encoding parameters in requests:

GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json

Note: The above example URI shows unencoded [ and ] characters simply for readability. In practice, these characters must be percent-encoded, per the requirements in RFC 3986.

Does this note apply only to requests? Or should responses also be percent-encoded, as in:

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page%5Boffset%5D=2",
    "last": "http://example.com/articles?page%5Boffset%5D=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON API paints my bikeshed!"
    }
  ]
}
1 Like
2

@mbuhot Since there was no answer here, may I ask what path you went?

3

Yes, those need to be percent encoded as well, any character which is in the reserved set of RFC3986 require encoding if they are intended to be passed through to the hypermedia format processing.

4

What I was wondering about was, if the encoding can (or should) be left to the consumer of the API. The goal would be to have a more human-readable output.

5

The consumer ultimately will need to be responsible for some amount of percent encoding of the brackets, e.g. sparse fieldsets in a query. However, if the consumer is simply following or applying a link, it should not require any processing from the consumer side.

I apologize if my previous response was unclear. Stating it a little differently, any URL you return which contains any character in the reserved set of RFC3986 is required to be percent encoded. The URL of hypermedia should be opaque to the consumer, you should not spend effort to make the link ‘href’ human readable.

If your concern is human readability, your focus should be on learning about and leveraging a hypermedia vocabulary for the services human readability, interactability, and interoperability. Take a look at my Hypermedia API Guidelines for a bit of information on the topic.

1 Like
6

Those posts are extremely helpful. Thank you so much.

7

You’re welcome, I’m glad you found them helpful.