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