I’ve been mulling this question for a while, and I don’t really see a good way to deal with it any other way than to allow resources that do not have an application/vnd.api+json representation.
Let’s say I have a resource that represents an attachment to an email message, of type attachment. This has a variety of fields, and is reasonably represented using application/vnd.api+json. But there are additional “resources” that are related to this that have no JSON:API representation, such as the raw content of the attachment, which could be anything, or an extracted plain text representation (of type text/plain).
I’d originally thought I could just add additional members to the links structure for the attachment resource, but I don’t think that’s valid in JSON:API 1.0. For JSON:API 1.1, it looks like Extension Relation Types could be used, but would be quite verbose, and I know my front-end developers would rebel.
So, my question:
Would it be reasonable for attachment resources to include relationships (perhaps content and plaintext in this example), with only the related link, which would respond with the appropriate non-application/vnd.api+json content?
As far as I understand the JSON:API specification the relationship object must point to a JSON:API resources.
Relationships
The value of the relationships key MUST be an object (a “relationships object”). Members of the relationships object (“relationships”) represent references from the resource object in which it’s defined to other resource objects.
For use cases like the once described by you I usually use an attribute, which value is a URL to fetch the data. E.g. an user resource may have an avatar attribute, which is an URL pointing to an image. Similar an attachment resource could have a content attribute, which is an URL to download the raw content of that attachment.
I have been in a project that dealt with this issue regarding multimedia data. For that we have introduced the concept of media object (type: "mediaObjects") with contentType and url as attributes. Like @jelhan mentioned, we use this for images, videos, and so, but this design should be able to support any content-type that is not an application/vnd.api+json.
So, you (also @cheeryfella) can find our design of media objects on the AlpineBits DestinationData standard, more precisely on section 5.2.5. If you want to understand what is our conceptualization of media objects, you can have a look at section 2.2.2.
Disclaimer: I’m not sure if this forum prohibits advertising, so I’m only sharing this regarding the adopted solution. I did work on this project and I’d love to talk about it here (since it’s an open source project), but I don’t know yet if that would be ok. If anyone wishes to know about it, feel free to reach me directly.
@jelhan, @claudenirmf: Using an attribute would indeed work. I can make the value an object with href, type, or other fields as needed if more than a simple href is needed.