hyper-schema, the self link, and response envelopes

[handrews]

Given a legacy API with a response envelope, is it reasonable to put a fragment on a self link pointing to the actual resource representation inside the envelope? In Draft 04, the "home" link relation was defined for this purpose, as far as I can tell. I was not a fan of its specific details, but adjusting for an envelope is a common use case for legacy APIs.

This, of course, is assuming we want to be able to work with legacy APIs at all.

Example instance returned from GET /foo/12345:

{
    "metaData": {...},
    "actualData": {...}
}

Example of self link with fragment (you also need extended templating to map the template variable for the envelope document to the id inside the envelope):

{
    "definitions": {
        "foo": {
            ...,
            "links": [{"rel": "self", "href": "/foo/{id}#/actualData"}]
        }
    },
    "type": "object",
    "properties": {
        "metaData": {...},
        "actualData": {"$ref": "#/definitions/foo"}
    },
    "links": [{
        "rel": "self",
        "href": "/foo/{id}",
        "hrefVars": {"id": "0/actualData/id"}
    }]
}

[awwright]

Can you define "response envelope" please?

[handrews]

It's the object consisting of two keys, metaData and actualData. All responses use that format, and put the actual representation under actualData. metaData has stuff like a success flag and custom error codes (yes, yes, I know, HTTP error codes, there's no need for a success flag, etc., etc., this is not something I would ever write but it is something I have to deal with).

So basically, let's say you create with a representation like {"bar": 42}. Then when you a GET on it you'll get back something like {"metaData": {"errors": []}, "actualData": {"bar": 42}}

[handrews]

Hmm... thinking about it more (despite putting this on hold all weekend to make sure I'd thought it through before filing it :-) I'm not actually sure how this would behave for PUT.

Assume that based on the self link we do a GET on /foo/12345 and get back

{
    "metaData": {"errors": []},
    "actualData": {"bar": 42}
}

We apply the fragment from the self link on the client side and get

{"bar": 42}

We change bar to 43 and want to PUT it back, still using the self link. What would the expected behavior be? The server doesn't see the fragment, obviously, but for a PUT it just expects the representation in the request. Not an envelope. So given that self link, can we just send

{"bar": 43}

because that's our modified representation and ignore the fragment, or does that fragment mean "put the thing you want to send in a document at this location, which would mean constructing and sending

{"actualData": {"bar": "43"}}

which is not actually what the resource expects on a PUT.

Blerg. I have never even thought about how to apply fragments when constructing documents. I kind of feel like that it should indicate the latter, which won't help me.

If that is how it should behave (construct a document with the representation at this location within the document, and PUT that), then it might be better to extend the hyper-meta-schema with some custom keywords for these legacy APIs as the use case is specific to the APIs in question.

[handrews]

I'm going to close this on the grounds that I can't figure out what the PUT behavior should be, and I don't think it's in-scope for JSON Schema to say anything about it.

Since fragments aren't sent to the server, the most logical interpretation of this is "apply the fragment to the document on the client side, and then PUT there result to the URI without the fragment", but that requires determining the semantics of applying the fragment. Which gets into JSON merging behavior, and we're way outside of the basic application/json media type here.

TL;DR: The legacy API behavior is weird and pathological, and not JSON Schema's problem.