Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Explain why to prefer "full resource when available" #9

Open
geemus opened this issue May 27, 2014 · 7 comments

Comments

Projects
None yet
3 participants
@geemus
Copy link
Member

commented May 27, 2014

ie vs summaries for list views and/or mechanisms to specify desired fields.

pulling this in as a distinct issue from #8

/cc @creynders

@creynders

This comment has been minimized.

Copy link

commented May 28, 2014

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

@geemus

This comment has been minimized.

Copy link
Member Author

commented May 29, 2014

@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

This comment has been minimized.

Copy link

commented May 30, 2014

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

This comment has been minimized.

Copy link
Member Author

commented May 30, 2014

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

This comment has been minimized.

Copy link

commented Jun 2, 2014

Good

@creynders

This comment has been minimized.

Copy link

commented Jun 4, 2014

@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

This comment has been minimized.

Copy link
Member Author

commented Jun 4, 2014

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.