Kävin tänään mielenkiintoista (melko teknistä) keskustelua Twitterissä ja Facebookissa siitä, miten REST API -rajapintojen sivuttaminen kannattaa nykyään toteuttaa.

Esiin nousi lähinnä kaksi kilpailevaa vaihtoehtoa:

(1) Sivuttaminen käyttäen HTTP-metadata-otsakkeita kuten X-Total-Count, X-Page-Count, jne. Tällöin varsinainen JSON-tieto voidaan palauttaa taulukkomuotoisena (array).

(2) Taulukon kuorruttaminen metadata-objektilla. Rajapinnan palauttama tieto on silloin esimerkiksi muodossa {"items":[...], "totalCount":123}.

Kummallakin vaihtoehdolla on hyviä ja huonoja puolia, jotka ovat pitkälti periaatteellisia. Itse olen nykyään enemmän käytännöllisyyden kuin periaatteellisuuden kannalla, joten kallistun tässä tapauksessa vaihtoehtoon (1).

Perusteluni tälle ovat:

  • Rajapinnan peruskäyttötapaus on mahdollisimman yksinkertainen, koska se palauttaa aina arrayn. Vastaanottajan ei tarvitse tehdä minkäänlaista sovitusta poimiakseen kuorruteobjektista erillisen "items"-attribuutin.

  • Sama periaate sopii sekä sivutettuihin että sivuttamattomiin rajapintoihin. Jos rajapinta ei tue sivuttamista, se ei palauta X-otsikoita. Kummassakin tapauksessa palautettu data on aina JSON-array. Vastaanottaja voi jättää sivuttamisen kokonaan huomiotta mikäli ei tarvitse sitä.

  • Rajapinnan kehittämisen voi huolehti aloittaa ilman sivutusta. Jos sivutusta myöhemmin kuitenkin huomataan tarvittavan, se voidaan laajentaa siististi aiemman rajapinnan päälle X-otsakkeilla, aiheuttamatta välittömiä yhteensopivuusongelmia.

  • X-otsakkeiden käyttö toimii nykyään selaimissa ongelmitta CORSin kanssa, kunhan rajapinta palauttaa asianmukaisen Access-Control-Expose-Headers-otsakkeen.

  • X-otsakkeet on nykyään helppo lukea selainten fetch()-rajapinnan palauttamasta vastineesta metodilla response.headers.getHeader('X-Total-Count').

Linkit keskusteluihin: https://twitter.com/kennu/status/890271051657220096 https://www.facebook.com/kennu/posts/10155607701699468

https://twitter.com/kennu/status/890271051657220096

Published 26.7.2017