Comments (7)
Thanks! BTW I too think you're doing a great job!
from http-api-design.
@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!
from http-api-design.
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:
- It automatically reduces the strain on the server
- It (partially) communicates the API
- It allows for automatic API consumer generation
- 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?
from http-api-design.
I'll try to respond to your points in order below:
- 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.
- I'm afraid I don't follow the API communication argument? Is it that in returning links you are providing this?
- 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.
- 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.
from http-api-design.
Good
from http-api-design.
@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.
from http-api-design.
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.
from http-api-design.
Related Issues (20)
- uuid in doubt HOT 4
- Dead link in about section HOT 1
- Guidance on implementing REST interfaces for state machine HOT 21
- I'm curious to know the reasoning for going with JSON Schemas instead of Swagger HOT 5
- How are you modeling authentication operation? HOT 1
- Using 409 Conflict for uniqueness checks HOT 2
- Create a website (Gitpage) HOT 3
- Traditional Chinese version, and add "List of Translations" HOT 5
- Consider adding language specific resources for implementing these principles HOT 1
- consider expanding error messaging as per white house guide HOT 7
- include more examples for main points HOT 9
- detail expansions
- Consider compatibility with jsonapi.org? HOT 8
- Why use UUID? HOT 12
- Paginating/ranging over non-unique fields HOT 15
- Pagination using Range cannot be consistent HOT 8
- Test Framework HOT 1
- The used time format is actually RFC5424, a subset of ISO8601 HOT 2
- Json with PLSQL ( PLJSON) HOT 1
- Links in README.md are 404 when viewed on Gitbook HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from http-api-design.