[Koha-devel] REST api / pagination

Thu Aug 24 18:08:02 CEST 2017

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

*F:* +44 (0) 800 756 6384

*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/
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20170824/e78679a0/attachment-0001.html>