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

Add Next link to JSON output from https://hypothes.is/api/search #2094

Closed
judell opened this Issue Mar 26, 2015 · 7 comments

Comments

Projects
None yet
4 participants
@judell
Copy link
Contributor

judell commented Mar 26, 2015

Consider: https://hypothes.is/api/search?limit=1000

Nothing I can see in the JSON tells me how to navigate past the first batch of 200.

@BigBlueHat

This comment has been minimized.

Copy link
Contributor

BigBlueHat commented Mar 27, 2015

👍 nearly added this when I was working with the API earlier.

To avoid a JSON format war (for now 😉) let's add a Link: header:

Link: <https://hypothes.is/api/search?offset=200>; rel="next"

...where the value of offset would be the value of limit if it was set. Default value of offset would match the default value of limit so a more complete response to /api/search (sans query params) would look like:

Link: <https://hypothes.is/api/search?limit=200>; rel="self"
Link: <https://hypothes.is/api/search?offset=200&limit=200>; rel="next"

That would also expose the default values...if someone cared to look. 😄

💭's?

@judell

This comment has been minimized.

Copy link
Contributor Author

judell commented Mar 27, 2015

FWIW most of the paging APIs I've used put the next link into the body of the JSON, it's more accessible there to both humans and machines. There aren't yet standard formats (I'll spare you my long screed on why OData should be that standard for things like this) so I don't see us violating any expectations with a link in the body.

@BigBlueHat

This comment has been minimized.

Copy link
Contributor

BigBlueHat commented Mar 27, 2015

@tilgovi

This comment has been minimized.

Copy link
Contributor

tilgovi commented Mar 27, 2015

Link headers are totally sensible. curl -I "https://api.github.com/search/code?q=addClass+user:mozilla"

@judell

This comment has been minimized.

Copy link
Contributor Author

judell commented Jun 12, 2015

Since posting this I've gotten used to (and we have documented) the limit=nnn&offset=nnn pattern so now I'm not feeling the need for this so much. I still like link-in-the-json-body for discoverability, though.

@BigBlueHat

This comment has been minimized.

Copy link
Contributor

BigBlueHat commented Jun 12, 2015

I'm all for hypermedia affordances into the body. It's just gonna take some
wrestling to get folks to come to consensus on where, what shape, etc.

Link headers were decided for us and have an undebatable (mostly) format. 😄

Also, we can (and should) do both--as you might want to do a HEAD check to see if anything's next.

@nickstenning

This comment has been minimized.

Copy link
Contributor

nickstenning commented Feb 10, 2016

Hi there! I'm going to close this as part of a clean-up of all issues currently open on this repo that represent ideas or features rather than reports of bugs or technical chores.

I want to be clear that this isn't intended to say anything at all about the content of this issue—it certainly doesn't mean we're no longer planning to do the work discussed here—just that we don't want to use GitHub issues to track feature requests or ideas, because the threads can get long and somewhat unwieldy.

If you're interested in what we are working on at the moment, you can check out our Trello board and, for a longer-term view, our roadmap.

And, if you're interested in following up on this issue, please do continue the discussion on our developer community mailing list. You might also want to check out our contributing guide.

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.