Explain why to prefer "full resource when available"

[interagent]

Explain why to prefer "full resource when available"

[creynders]

Thanks! BTW I too think you're doing a great job!

[geemus]

@creynders Thanks, glad you like it!

Some people will always need the expanded version, so if you can only choose one representation, choose expanded. At least initially this simplifies usage (and implementation). And you can always add contraction/limiting mechanisms if/when they become necessary, though I suspect that these would remain better as opt-in for optimization purposes than being the default.

Hope that clarifies, but certainly happy to discuss further and would love any suggestions you might have about how we can clarify this within the document. Thanks!

[creynders]

Thanks, glad you like it!

Absolutely, it's sorely needed!

Some people will always need the expanded version, so if you can only choose one representation, choose expanded.

I can't agree with that. I'm a strong proponent of returning as little as possible as fast as possible, but with clear means on how to retrieve the full resources if necessary.

E.g.

{
    "resource":[
        {
            "id":"91423376-d59e-4ab4-96c8-2b89a6a7d917",
            "title":"Whatever",
            "link" : {
                "href":"/api/foos/91423376-d59e-4ab4-96c8-2b89a6a7d917"
            }
        },
        {
            "id":"b4157492-38b2-4357-938b-5c44423d2931",
            "title":"SingleActor",
            "link" : {
                "href":"/api/foos/b4157492-38b2-4357-938b-5c44423d2931"
            }
        }
    ],
    "schema" : {
        "id": "unique id",
        "title" : "Describes the resource",
        "answerToLifeTheUniverseAndEverything": "42",
        "address" : "Some place"
    }
}

This approach has a number of benefits:

1. It automatically reduces the strain on the server
2. It (partially) communicates the API
3. It allows for automatic API consumer generation
4. It's far more readable than dumping full resources

All the API consumer needs to know is an entry point and the means to expand this if necessary (i.e. through a parameter or whatever) with a possible wildcard value to allow for retrieval of full resources.

At least initially this simplifies usage (and implementation)

I don't really agree with this either. Implementation wise the above is pretty trivial.

Any thoughts?

[geemus]

I'll try to respond to your points in order below:

1. It may reduce the strain, but in our experience at least, most of the strain is connect and db based, so removing some attributes might not impact it that much. Similarly, minimizing by default can lead to many use cases requiring additional requests to complete, so it may be that a single slower request would out perform several somewhat faster requests. That said, a lot of this is very implementation specific, so it is difficult to make a generic argument around performance/strain.
2. I'm afraid I don't follow the API communication argument? Is it that in returning links you are providing this?
3. We are doing API generation for full responses already with interagent/heroics and interagent/schematics, I'm not sure I understand why reduced/full makes a difference here.
4. Readability is difficult to say, I think it depends on the use case. Having fewer params gives you less to look through, but I'm not sure it gains you much if you simply realize you need to make one or more additional API calls to actually get the information you want.

Ultimately I think a big part of the question is what can be expected to be the most common use case(s) for end users. If they are likely to always (or almost always) choose the expanded versions, as I suspect they might be, then making the default differ from this seems counter-productive. This keeps the problem of dealing with the additional strain on the server side, where I think it often belongs (as otherwise many different people all have to solve the same problem).

My argument about simplifying usage and implementation was meant to point to the fact that if you only have to implement fully expanded things, it saves you have to implement something that can conditionally return different kinds of output based on some params and saves clients from needing to know that this is the case and that passing additional params is sometimes required.

[teachar]

Good

[creynders]

@geemus Took some time to think this through. I definitely agree with 3/ reduced/full doesn't make a difference there.
Expounding on 2/ I guess (to me and in my scenario) the fact that you return the minimum amount of data on a resource communicates more clearly that there's more to be found, when asked explicitly. While when resources are returned in full, it seems less clear whether it is in full or partial. (I mean, obviously in your case I know it's in full, since you advocate it as best practice, but when glancing through 3rd party API's I've been in doubt several times.)
That's why I prefer a more explicit approach.

But to be honest I'm swaying towards the "it depends" stance, since I do agree this

If they are likely to always (or almost always) choose the expanded versions, as I suspect they might be, then making the default differ from this seems counter-productive.

... makes a lot of sense. Still, I'm not entirely sure whether it should be advocated as best practice. Think I'll have to think on this some more. Seems this is more of an intuitive thing to me (maybe for all the wrong reasons) than a really thought out strategy.

[geemus]

Thanks again for a civil/ongoing discussion, I think it is helpful and hopefully helps both of us solidify our thinking.

One thing I didn't really go into too much is that one of my big goals was to make our API as approachable and easy to use as possible. One big part of that equation, in my mind anyway, is to reduce/eliminate statements that run something like "it ALWAYS does X, EXCEPT when Y". Having some full and some partial as the default runs pretty strongly against that. Partial responses certainly have a lot of advantages (especially for some particular use cases and optimization), but it did not seem like it made it faster or easier for brand new users to get what they needed.

I've certainly also been in the "is this all of it?" place before when interacting with other APIs, and along with trying to minimize exceptions, it seemed like a good reason to keep it simple and non-exceptional. I guess in many ways my stance, starting from this, is toward starting with simple/explicit and expanding in to more complex (but probably still explicit) behaviors as they are needed.

Hope maybe that explains some of the reasoning and basis for that world view at least a bit more clearly. Some of the concerns are certainly more to do with UX type concerns that traditional API concerns, but I think it is beneficial to apply that lens as well.