Comments (7)
Great question, and as you hint, not one that lends itself easily to a universal answer. So, in short, "it depends". I'll add some brief thoughts though.
First off, I think in general that it is often best to start with a really generic version of things. ie in this case, orgs and apps distinctly (and you can pull back the list and count yourself). This is not what either the UI or server want to be doing, per se, but it supports both and most anything else a different UI might want. I think having that foundation is really valuable, especially since UI needs often change (quickly) it can be dangerous to chase it too quickly.
That said, when patterns have settled down, I think it can be quite valuable to add things to help in this case. In your example you mention counts as being an important thing. I suspect I would add that value in a more accessible way, albeit one a bit different from yours.
Note that I haven't followed this approach in practice, so there may be hidden gotchas, but my inclination would be toward something like:
curl https://service.com/orgs/{org_id}/stats/{resource_id}
Initially it could just support the resource_id users
and the serialization might only include count
, but it seems like a generic-enough pattern that it could nicely accommodate a lot of similar features as needed while avoiding the need to change existing production endpoints.
Hope that sheds some light, I'd certainly be happy to discuss some more (I realize my response is pretty hyper-focused on the particulars of this example after all). I think there will always be tension when you control both a client and api to try to mesh them tightly, but I think the threat of overfitting is very real and problematic (especially if you have or hope to have additional clients or usage outside your control).
Thanks!
from http-api-design.
i'm faced with the same problem.
i've seen a very elegant approach for determining counts... request a range of 0 (or 1) items and inspect the response to determine the count.
EDIT: for context, https://github.com/persvr/pintura#pagingrange-requests is what my pagination scheme is based on
request:
Range: items=0-0
response:
Content-Range: items 0-0/80
based on the Content-Range header in this response i can see that 80 items match my request.
then, in order to reduce the number of http requests from the client, provide a server endpoint to handle batched requests - something along the lines of https://github.com/persvr/pintura#bulk-updates-and-comet. to implement this on the client, i use a utility for making requests to the server and this gives me a way to collate the requests together and then make one request to the server at the end of an event turn.
maybe this won't suit everyone but i think it's a reasonable solution to this problem and may give some ideas about how to approach this in a way that you're comfortable with.
from http-api-design.
@neonstalwart nice. Yeah, for counts in particular that definitely seems like an elegant option.
from http-api-design.
CH counts ?
from http-api-design.
@camcam5313 CH? Not sure I follow, could you elaborate? Thanks.
from http-api-design.
Thanks, all. I think the particulars of my example are obscuring the larger question, which is just: what rules or criterion do you use to determine which properties are included in a resource? Given that any resource will satisfy an infinite number of predicates, which ones should the server include in responses?
I'm currently trying to attack this from opposite ends, in the hopes that they'll meet in the middle. First, how do you establish a baseline set of properties? Do you just recapitulate your storage schema? And second, are there any rules-of-thumb for readily determining that a given datapoint should not be exposed on that resource?
To give you an example of what I think I'm looking for, here's something I'm considering:
- any property that can be modified by a resource ought to be readable via that same resource
I'm trying to articulate similar guidelines that might be used to sort UI-driven changes between base resources and other API paths.
from http-api-design.
@tomrogers42 yeah, as always, it can be tricky to generalize effectively.
I think it can be good to start with some foundation/baseline. For instance, we just asserted that everything should have, at least a uuid, created_at and updated_at timestamps. Occasionally not all are needed (things that can be created, but never changed, for instance, don't REALLY need updated_at). That said, always having it doesn't really hurt anything and the consistency has some value of it's own.
I think anything readable should be writable is a great additional guideline. I think a lot about input/output parity when I'm working on these sorts of things. So in addition to just saying that they should be similar, I try (where it makes sense) to even make the json format of the data similar. The more similarity the fewer the number of new and/or surprising things you have to figure out along the way.
I think you should be wary of recapitulating storage schema. In some cases that is just fine, but in other cases it can be symptomatic of a leaky abstraction. In many cases the end users can be provided a better naming or more useful arrangement than what the db holds explicitly (this seems likely to be more true the more legacy the datastore is). With greenfield things, however, it seems likely that the datastore and API data will track pretty closely, at least initially.
Ideally I would provide some additional guidelines, but I'm not sure what else can be easily generalized toward. So hopefully some further thoughts on your questions and points will still be helpful, even if we haven't necessarily arrived at a clear checklist quite yet. Definitely some extra stuff we could extract from here to improve on the guide though already, I think/hope.
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.