indicating RESTful JSON in responses

[mamund]

would be good to see some runtime indication that the response follows the RESTful JSON convention. having something appearing at runtime would help when writing general clients that use confirmation of the use of RESTful JSON to improve parsing and rendering of the response.

I see three reasonable ways to do this:

• link relation value in the header
• link relation value in the body
• link relation value in the content-type string

For example, the appearance of the `profile' link relation in the header (alal RFC6906)

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: XXX
Link: <http://restfuljson.org/>; rel="profile"

Or the profile appearing in the body:

{
    "profile_url": "http://restfuljson.org/",
    "url": "/articles/17",
    "title": "Article Title",
    "body": "The body of the article.",
    "author_url": "/authors/42",
    "categories": [
        {
            "url": "/categories/29",
            "name": "Category A"
        },
        {
            "url": "/categories/33",
            "name": "Category B"
        }
    ],
    "docs_url": "/docs/article"
}

Or possibly as part of the content-type string:

HTTP/1.1 200 OK
Content-Type: application/json;profile=http://restfuljson.org/
Content-Length: XXX

This may also mean the URL should be a URI (non-resolvable) that contains more meta-data (e.g. versioning info to handle future changes, etc.)

FWIW, i use the third option since it is easily available for low-level parsing within a client app.

[fosrias]

@mamund We did discuss doing a vnd media-type. However, you are recommending adding a SHOULD to the current conventions along the lines of your above suggestions, IIUC?

[smizell]

@mamund what do you see as the use case for adding this information in the response?

---

I'd like to add a couple of thoughts here to provide a backdrop to the discussion. RESTful JSON exists as a way to help people in the world of tools like OpenAPI spec and formats like application/json to add link conventions to their API. This works well for domain-specific clients because the client developers will read the API documentation to understand the semantics of the payload. From there they will understand what is and isn't a link. This is a pattern that people are already following.

I don't think RESTful JSON lends itself to being a format consumable by generic clients looking for links. This is because in RESTful JSON, we encourage users to use the case that best fits their situation, either snake or camel case. Additionally, I've ran into situations where API implementations had some collision with a url property, so they used selfUrl in its place.

Because of this, my recommendation to API developers has been that it's better to point client developers to API documentation in the API responses than to RESTful JSON directly. There, client developers will find semantics and recommendations for processing links. It's also good to point to RESTful JSON in the API documentation for further recommendations.

A practice I've done so far has been to mark certain parts of the JSON Schema as a "link" or "URL" format. Clients could consume an OpenAPI document, pull resources and links from it, and then be able to pragmatically figure out links in the payloads. This would be a different approach than encouraging client developers to look for properties that are suffixed with _url either in their clients or as they read the code.

[mamund]

well, if you don't see this a useful for anything other than pre-established conventions between client and server, then i'd skip providing any indication at runtime that the response is using RESTful JSON.

you can close this out.

[smizell]

So far I have not personally had that use case, but I'm curious to hear other use cases for sure! :) I think @fosrias also has some thoughts around a more general-purpose use case as well. Was your idea to look for _url to find links in the response?

Also, it seems like if a profile was used, it would need to be tied to a specific case (e.g. snake case with _url).

[smizell]

@mamund We've registered a media type with IANA. Hoping this works for your use case :D Thanks for the feedback.

[mamund]

cool. thanks.