[Koha-devel] REST api / pagination

Fri Aug 25 13:49:20 CEST 2017

Yeah, I've been playing with a helper function to implement it generically.
We could imitate github's implementation of the 'rel' attributes.

El vie., 25 ago. 2017 a las 8:36, Kyle Hall (<kyle.m.hall at gmail.com>)
escribió:

> I like the rfc5988 idea. How practical will it be to implement this in our
> current API?
>
>
> <https://secure2.convio.net/cffh/site/Donation2?df_id=1395&FR_ID=4715&PROXY_ID=2706639&PROXY_TYPE=20&1395.donation=form1&s_src=CHORUS&s_subsrc=CHAADOEB>
>
> http://www.kylehall.info
> ByWater Solutions ( http://bywatersolutions.com )
> Meadville Public Library ( http://www.meadvillelibrary.org )
> Crawford County Federated Library System ( http://www.ccfls.org )
>
> On Thu, Aug 24, 2017 at 12:08 PM, Renvoize, Martin <
> martin.renvoize at ptfs-europe.com> wrote:
>
>> This:
>> http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#pagination
>> tends to be my go to advise on paging.
>>
>> So, it suggests (and I agree) that paging should be handled in the
>> headers rather than producing an envelope as per option c.
>>
>> This has the advantage in my opinion that we can add the additional
>> details from c without changing the body of the response at all and thus
>> save an api version jump.
>>
>> I also tend to try and use cursors where I can rather than pages.. just
>> in case the data changes beneath you ;).
>>
>> Example of how I do it in a Mojo app using dbic and openapi:
>> https://gist.github.com/mrenvoize/de0f30716fec8217a15b57d920fbdace
>>
>> Hope that helps.
>>
>>
>> *Martin Renvoize*
>>
>> Development Manager
>>
>>
>>
>>
>> *T:* +44 (0) 1483 378728 <+44%201483%20378728>
>>
>> *F:* +44 (0) 800 756 6384 <+44%20800%20756%206384>
>>
>> *E:* martin.renvoize at ptfs-europe.com
>>
>> www.ptfs-europe.com
>>
>>
>>
>> <https://www.ptfs-europe.com>
>>
>>
>>
>> Registered in the United Kingdom No. 06416372   VAT Reg No. 925 7211 30
>>
>> The information contained in this email message may be privileged,
>> confidential and protected from disclosure. If you are not the intended
>> recipient, any dissemination, distribution or copying is strictly
>> prohibited. If you think that you have received this email message in
>> error, please email the sender at info at ptfs-europe.com
>>
>>
>> On 24 August 2017 at 16:38, Michael Hafen <michael.hafen at washk12.org>
>> wrote:
>>
>>> While I agree that adding data to and endpoint wouldn't require
>>> versioning the api; what option C represents is a fundamental change to the
>>> data structure that the endpoint returns.  Assuming the examples of
>>> returned data in options A and B represent the current api that is.
>>> I think that really the question is are we going to version the api or
>>> not.  If we control all the clients that use the api, then versioning may
>>> be unnecessary, since we can change the api calls in the client as
>>> necessary when the api changes.  That probably isn't the case though.
>>> I'm in favor of option A, even though it would mean another endpoint(s)
>>> to get the total number of results to aid pagination.  I've seen an api
>>> like that, and while it isn't as efficient to make the extra api call, it
>>> is manageable.
>>> Though I would also be in favor of option C if we all agree that
>>> versioning the api is necessary in this case.
>>>
>>> On Thu, Aug 24, 2017 at 9:31 AM, Kyle Hall <kyle.m.hall at gmail.com>
>>> wrote:
>>>
>>>> I'd vote for C with no api versioning change. I think the *addition* of
>>>> data does not warrant any version change.
>>>>
>>>> The alternative would be A + another endpoint to just get the number of
>>>> results.
>>>>
>>>> Kyle
>>>>
>>>>
>>>> <https://secure2.convio.net/cffh/site/Donation2?df_id=1395&FR_ID=4715&PROXY_ID=2706639&PROXY_TYPE=20&1395.donation=form1&s_src=CHORUS&s_subsrc=CHAADOEB>
>>>>
>>>> http://www.kylehall.info
>>>> ByWater Solutions ( http://bywatersolutions.com )
>>>> Meadville Public Library ( http://www.meadvillelibrary.org )
>>>> Crawford County Federated Library System ( http://www.ccfls.org )
>>>>
>>>> On Thu, Aug 24, 2017 at 10:50 AM, Tomas Cohen Arazi <
>>>> tomascohen at gmail.com> wrote:
>>>>
>>>>> Hi there, I'm currently implementing a couple endpoints for
>>>>> acquisitions-related stuff and also QAing existing patches introducing
>>>>> endpoints.
>>>>>
>>>>> One of the things that need to be done (which I did for my own
>>>>> endpoint for vendors / bug 18120) is migrating them to
>>>>> Mojolicious::Plugin::OpenAPI instead of (the deprecated)
>>>>> Mojolicious::Plugin::Swagger2.
>>>>>
>>>>> I noticed there's lack of a generic way to deal with pagination. There
>>>>> are a couple options we could consider, but I would like to hear the
>>>>> opinion of UI people, which are the ones that will take advantage or suffer
>>>>> what we do on the backend :-D
>>>>>
>>>>> a)  GET /patrons?page=1&per_page=3 => [ {borrower1}, {borrower2},
>>>>> {borrower3} ]
>>>>> b)  GET /patrons?offset=0&limit=3 => [ {borrower1}, {borrower2},
>>>>> {borrower3} ]
>>>>>
>>>>> Lari proposed another one, which tackles an issue we could have on the
>>>>> UI (knowing the total, calculating pages, etc):
>>>>>
>>>>> c) GET /patrons?page=1&per_page=3 { total: 50000, results: [
>>>>> {borrower1}, {borrower2}, {borrower3} ] }
>>>>>
>>>>> (c) has the problem that it would mean we need to change the current
>>>>> resposes for list operations on the already implemented endpoints. I'm not
>>>>> sure at this point we would need to shift api version (v2?), I would vote
>>>>> against, but here we have the chance to hear people using the API.
>>>>>
>>>>> Looking forward to your comments as my current dev work completion
>>>>> depends on it :-D
>>>>>
>>>>> --
>>>>> Tomás Cohen Arazi
>>>>> Theke Solutions (https://theke.io <http://theke.io/>)
>>>>> ✆ +54 9351 3513384 <+54%209%20351%20351-3384>
>>>>> GPG: B2F3C15F
>>>>>
>>>>> _______________________________________________
>>>>> Koha-devel mailing list
>>>>> Koha-devel at lists.koha-community.org
>>>>> http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
>>>>> website : http://www.koha-community.org/
>>>>> git : http://git.koha-community.org/
>>>>> bugs : http://bugs.koha-community.org/
>>>>>
>>>>
>>>>
>>>> _______________________________________________
>>>> Koha-devel mailing list
>>>> Koha-devel at lists.koha-community.org
>>>> http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
>>>> website : http://www.koha-community.org/
>>>> git : http://git.koha-community.org/
>>>> bugs : http://bugs.koha-community.org/
>>>>
>>>
>>>
>>>
>>> --
>>> Michael Hafen
>>> Washington County School District Technology Department
>>> Systems Analyst
>>>
>>>
>>> _______________________________________________
>>> Koha-devel mailing list
>>> Koha-devel at lists.koha-community.org
>>> http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
>>> website : http://www.koha-community.org/
>>> git : http://git.koha-community.org/
>>> bugs : http://bugs.koha-community.org/
>>>
>>
>>
> _______________________________________________
> Koha-devel mailing list
> Koha-devel at lists.koha-community.org
> http://lists.koha-community.org/cgi-bin/mailman/listinfo/koha-devel
> website : http://www.koha-community.org/
> git : http://git.koha-community.org/
> bugs : http://bugs.koha-community.org/

-- 
Tomás Cohen Arazi
Theke Solutions (https://theke.io <http://theke.io/>)
✆ +54 9351 3513384
GPG: B2F3C15F
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20170825/8a579243/attachment.html>