Cyfroteka.pl

klikaj i czytaj online

Cyfro
Czytomierz
00434 008263 18429711 na godz. na dobę w sumie
Interfejs API. Strategia programisty - ebook/pdf
Interfejs API. Strategia programisty - ebook/pdf
Autor: , , Liczba stron: 200
Wydawca: Helion Język publikacji: polski
ISBN: 978-83-283-0558-8 Data wydania:
Lektor:
Kategoria: ebooki >> komputery i informatyka >> programowanie >> inne - programowanie
Porównaj ceny (książka, ebook (-20%), audiobook).

Poznaj potencjał interfejsów API!

Internet to gigantyczna sieć urządzeń połączonych ze sobą. Jego potencjał wykorzystują wszyscy i każdy jest świadom tego, że pojedyncze urządzenie bez połączenia z siecią nic nie znaczy. Podobnie jest z systemami informatycznymi. Możliwość integracji z siecią, tworzenia rozszerzeń oraz wymiany danych pomaga twórcom aplikacji rozwinąć skrzydła i odnieść sukces na szeroką skalę. Zastanawiasz się, jak otworzyć Twój system na świat? Interfejs API to jedyna droga!

Sięgnij po tę książkę i przekonaj się, jak przygotować wygodny interfejs API, z którego programiści będą korzystali z przyjemnością. Na kolejnych stronach znajdziesz kluczowe zasady projektowania interfejsów API, sposoby zabezpieczania API oraz zarządzania użytkownikami. Ponadto dowiesz się, jak zarządzać ruchem sieciowym, obsługiwać interfejs API oraz mierzyć sukces Twojego API. Na sam koniec zobaczysz, jak zaangażować projektantów w proces adaptacji. Ta książka jest doskonałym źródłem informacji dla wszystkich osób chcących zrozumieć, czym są interfejsy API, jak wykorzystać drzemiący w nich potencjał oraz jak uniknąć typowych zagrożeń i problemów. Twoja lektura obowiązkowa!

Wszystko, co powinieneś wiedzieć o interfejsach API!

Znajdź podobne książki Ostatnio czytane w tej kategorii

Darmowy fragment publikacji:

Tytuł oryginału: APIs: A Strategy Guide Tłumaczenie: Piotr Pilch ISBN: 978-83-283-0555-7 © 2015 Helion S.A. Authorized Polish translation of the English edition of APIs: A Strategy Guide, ISBN 9781449308926 © 2012 Evolved Media. This translation is published and sold by permission of O’Reilly Media, Inc., which owns or controls all rights to publish and sell the same. All rights reserved. No part of this book may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording or by any information storage retrieval system, without permission from the Publisher. Wszelkie prawa zastrzeżone. Nieautoryzowane rozpowszechnianie całości lub fragmentu niniejszej publikacji w jakiejkolwiek postaci jest zabronione. Wykonywanie kopii metodą kserograficzną, fotograficzną, a także kopiowanie książki na nośniku filmowym, magnetycznym lub innym powoduje naruszenie praw autorskich niniejszej publikacji. Wszystkie znaki występujące w tekście są zastrzeżonymi znakami firmowymi bądź towarowymi ich właścicieli. Autor oraz Wydawnictwo HELION dołożyli wszelkich starań, by zawarte w tej książce informacje były kompletne i rzetelne. Nie biorą jednak żadnej odpowiedzialności ani za ich wykorzystanie, ani za związane z tym ewentualne naruszenie praw patentowych lub autorskich. Autor oraz Wydawnictwo HELION nie ponoszą również żadnej odpowiedzialności za ewentualne szkody wynikłe z wykorzystania informacji zawartych w książce. Wydawnictwo HELION ul. Kościuszki 1c, 44-100 GLIWICE tel. 32 231 22 19, 32 230 98 63 e-mail: helion@helion.pl WWW: http://helion.pl (księgarnia internetowa, katalog książek) Drogi Czytelniku! Jeżeli chcesz ocenić tę książkę, zajrzyj pod adres http://helion.pl/user/opinie/inapst Możesz tam wpisać swoje uwagi, spostrzeżenia, recenzję. Printed in Poland. • Kup książkę • Poleć książkę • Oceń książkę • Księgarnia internetowa • Lubię to! » Nasza społeczność Spis tre(cid:316)ci Przedmowa ......................................................................................9 1. Mo(cid:348)liwo(cid:316)ci interfejsów API .......................................................... 13 15 17 17 18 Dlaczego napisano t(cid:246) ksi(cid:241)(cid:276)k(cid:246)? Dla kogo przeznaczona jest ta ksi(cid:241)(cid:276)ka? Czym jest interfejs API? Czym interfejs API ró(cid:276)ni si(cid:246) od witryny internetowej? Interfejsy API i witryny internetowe maj(cid:241) jednak(cid:276)e wiele wspólnego 20 21 Kto korzysta z interfejsu API? 21 Typy interfejsów API 23 Dlaczego teraz? Interfejsy API jako strategia biznesowa .......................................25 28 Rozwój interfejsów API 30 Dlaczego interfejs API mo(cid:276)e okaza(cid:232) si(cid:246) potrzebny? 30 31 2. 32 Potrzebujesz drugiej aplikacji dla urz(cid:241)dze(cid:254) przeno(cid:264)nych Klienci lub partnerzy pytaj(cid:241) o interfejs API Witryna internetowa zaczyna by(cid:232) u(cid:276)ywana do wyodr(cid:246)bniania wy(cid:264)wietlanych danych Wymagasz wi(cid:246)kszej elastyczno(cid:264)ci w zakresie udost(cid:246)pniania tre(cid:264)ci Istniej(cid:241) dane, które maj(cid:241) zosta(cid:232) udost(cid:246)pnione Konkurencja z bran(cid:276)y korzysta z interfejsu API Chcesz umo(cid:276)liwi(cid:232) potencjalnym partnerom poznanie nowo(cid:264)ci Wymagasz skalowania integracji z klientami i partnerami Interfejs API ulepsza architektur(cid:246) techniczn(cid:241) 32 33 33 34 34 36 3. (cid:292)a(cid:295)cuch warto(cid:316)ci interfejsu API ................................................... 37 38 41 42 45 46 Metody u(cid:276)ycia prywatnego interfejsu API Zalety prywatnych interfejsów API Zagro(cid:276)enia zwi(cid:241)zane z prywatnymi interfejsami API Definiowanie (cid:228)a(cid:254)cucha warto(cid:264)ci: zadawanie kluczowych pyta(cid:254) Tworzenie (cid:228)a(cid:254)cucha warto(cid:264)ci prywatnego interfejsu API 3 Kup książkęPoleć książkę Tworzenie (cid:228)a(cid:254)cucha warto(cid:264)ci publicznych interfejsów API Metody wykorzystania publicznego interfejsu API Zalety publicznych interfejsów API Zagro(cid:276)enia zwi(cid:241)zane z publicznymi interfejsami API Przemiana: publiczny interfejs API zamiast prywatnego, prywatny interfejs zamiast publicznego Netflix: zamiana publicznego interfejsu API na prywatny Modele biznesowe z interfejsami API u(cid:276)ywane do wspó(cid:228)pracy z partnerami Zwi(cid:246)kszanie zasi(cid:246)gu: wi(cid:246)cej aplikacji, wi(cid:246)cej platform Osi(cid:241)ganie po(cid:264)redniego dochodu Zwi(cid:246)kszanie innowacji we wspó(cid:228)pracy z partnerami Zwi(cid:246)kszanie warto(cid:264)ci aplikacji poprzez integracj(cid:246) Wariant u(cid:276)ycia po cz(cid:246)(cid:264)ci darmowy, a po cz(cid:246)(cid:264)ci p(cid:228)atny 47 48 51 52 53 54 56 56 57 58 58 59 Postrzeganie modeli biznesowych interfejsów API przez firm(cid:246) ProgrammableWeb.com Interfejsy API wymagaj(cid:241) sponsora biznesowego Typy strategii zwi(cid:241)zanych z interfejsami API Strategie dotycz(cid:241)ce prywatnych interfejsów API Strategie dotycz(cid:241)ce publicznych interfejsów API Okre(cid:264)lanie jasnego celu biznesowego Okre(cid:264)lenie wizji dotycz(cid:241)cej interfejsu API Podstawy strategii dotycz(cid:241)cej interfejsu API 60 4. Przygotowywanie strategii produktów z interfejsami API .........65 66 66 68 69 70 71 72 73 74 76 5. Kluczowe zasady projektowania interfejsów API .......................81 82 83 85 85 86 87 88 89 90 91 Odró(cid:276)nij w(cid:228)asny interfejs API Zapewnij (cid:228)atwo(cid:264)(cid:232) testowania i u(cid:276)ywania interfejsu API Zapewnij (cid:228)atwo(cid:264)(cid:232) zrozumienia interfejsu API Nie rób niczego dziwnego Mniej znaczy wi(cid:246)cej Ukierunkowanie na konkretny segment projektantów Projektowanie pod k(cid:241)tem projektantów Projektowanie pod k(cid:241)tem u(cid:276)ytkowników aplikacji Projektowanie interfejsów API dla konkretnych grup odbiorców Najlepsze praktyki zwi(cid:241)zane z projektem interfejsów API Tworzenie zespo(cid:228)u Promotor projektantów Zastrze(cid:276)enia dotycz(cid:241)ce interfejsów API 4 (cid:95) Spis tre(cid:316)ci Kup książkęPoleć książkę Kwestie techniczne projektu interfejsów API Us(cid:228)uga REST Przyk(cid:228)ad: projektowanie z wykorzystaniem pragmatycznej us(cid:228)ugi REST Kontrola wersji i projekt interfejsu API Projektowanie infrastruktury dla interfejsów API Centrum danych czy chmura? Strategie buforowania Kontrolowanie ruchu sieciowego generowanego przez interfejsy API 91 92 97 100 106 106 107 109 6. Zabezpieczenia interfejsów API Szyfrowanie Wykrywanie zagro(cid:276)e(cid:254) i zapobieganie im i zarz(cid:233)dzanie u(cid:348)ytkownikami ...................................................... 111 112 Zarz(cid:241)dzanie u(cid:276)ytkownikami 113 Czy niezb(cid:246)dne jest rozpoczynanie od podstaw? Pytania, które nale(cid:276)y zada(cid:232) odno(cid:264)nie do zarz(cid:241)dzania u(cid:276)ytkownikami Identyfikacja Uwierzytelnianie: potwierdzanie to(cid:276)samo(cid:264)ci u(cid:276)ytkownika „Wstrzykiwanie” kodu SQL Ataki z wykorzystaniem formatów XML i JSON Maskowanie danych Nazwy u(cid:276)ytkowników i has(cid:228)a Uwierzytelnianie oparte na sesji Inne metody uwierzytelniania Protokó(cid:228) OAuth Ulepszanie uwierzytelniania za pomoc(cid:241) protoko(cid:228)u SSL 113 114 116 116 117 118 118 120 122 123 124 124 125 126 126 126 7. Kwestie prawne zwi(cid:233)zane ze strategi(cid:233) interfejsu API .............. 129 130 130 133 135 136 137 137 Umowy i warunki u(cid:276)ytkowania Zasady prywatno(cid:264)ci Zasady utrzymywania danych Przypisywanie w(cid:228)a(cid:264)ciciela tre(cid:264)ci i budowanie (cid:264)wiadomo(cid:264)ci marki Reagowanie na niew(cid:228)a(cid:264)ciwe u(cid:276)ycie Zarz(cid:241)dzanie prawami Praktyka: zarz(cid:241)dzanie prawami w organizacji NPR Ogólne zalecenia Zalecenia dotycz(cid:241)ce ochrony danych interfejsu API Zalecenia dotycz(cid:241)ce zabezpiecze(cid:254) interfejsów API Spis tre(cid:316)ci (cid:95) 5 Kup książkęPoleć książkę 8. Obs(cid:293)uga interfejsu API i zarz(cid:233)dzanie nim ................................... 139 140 Obs(cid:228)uga interfejsu API Informacje operacyjne na (cid:276)(cid:241)danie: strona statusu interfejsu API Radzenie sobie z problemami operacyjnymi Umowy SLA Zarz(cid:241)dzanie problemami Monitorowanie i wsparcie operacyjne Dokumentowanie interfejsu API Zestaw procedur operacyjnych 141 142 143 143 144 145 147 148 148 152 154 155 9. Okre(cid:316)lanie miary sukcesu interfejsu API .................................... 159 160 Zarz(cid:241)dzanie ruchem sieciowym na poziomie biznesowym Operacyjne zarz(cid:241)dzanie ruchem sieciowym Zarz(cid:241)dzanie ruchem sieciowym i skalowalno(cid:264)(cid:232) Bramy interfejsów API Metody zarz(cid:241)dzania ruchem sieciowym Obs(cid:228)uga metryk interfejsów API Dlaczego gromadzone s(cid:241) wzorce wykorzystania na potrzeby metryk? (cid:275)(cid:241)dania i odpowiedzi Wy(cid:264)wietlenia Lojalno(cid:264)(cid:232) 161 162 162 163 164 166 166 167 10. Anga(cid:348)owanie projektantów w proces adaptacji ....................... 173 174 174 Co motywuje projektantów? Kluczowe elementy programu dla projektantów Metryki zwi(cid:241)zane z efektywno(cid:264)ci(cid:241) Metryki zwi(cid:241)zane z wydajno(cid:264)ci(cid:241) Metryki operacyjne Kluczowe pytania zwi(cid:241)zane z wydajno(cid:264)ci(cid:241) interfejsów API Produkt (czyli najpierw musisz dysponowa(cid:232) znakomitym interfejsem API!) Dost(cid:246)p do interfejsu API i jego twórcy Warunki biznesowe i oczekiwania wzgl(cid:246)dem umów SLA Tre(cid:264)(cid:232) (cid:263)wiadomo(cid:264)(cid:232) istnienia interfejsu API Skoncentruj si(cid:246) na pe(cid:228)nym komforcie pracy projektantów Spo(cid:228)eczno(cid:264)(cid:232) 175 175 176 177 177 178 179 6 (cid:95) Spis tre(cid:316)ci Kup książkęPoleć książkę Anatomia portalu projektantów Dzia(cid:228)ania zalecane i niezalecane w procesie anga(cid:276)owania projektantów 179 Dzia(cid:228)ania zalecane Dzia(cid:228)ania niezalecane 184 184 188 11. Epilog: to dopiero pocz(cid:233)tek ..........................................................191 Skorowidz .................................................................................... 193 Spis tre(cid:316)ci (cid:95) 7 Kup książkęPoleć książkę 8 (cid:95) Spis tre(cid:316)ci Kup książkęPoleć książkę ROZDZIA(cid:292) 5. Kluczowe zasady projektowania interfejsów API W pocz(cid:241)tkowych etapach rozwoju projekt interfejsów API stanowi sztuk(cid:246). Niemniej jednak zdobyto wystarczaj(cid:241)ce do(cid:264)wiadczenie do tego, aby opra- cowa(cid:232) warto(cid:264)ciow(cid:241) list(cid:246) b(cid:228)(cid:246)dów do unikania, a tak(cid:276)e zasady zapewniaj(cid:241)ce powodzenie. (cid:275)eby w(cid:228)a(cid:264)ciwie zaprojektowa(cid:232) interfejs API, konieczne b(cid:246)- dzie uwzgl(cid:246)dnienie wi(cid:246)kszo(cid:264)ci zagadnie(cid:254) poruszonych w tej ksi(cid:241)(cid:276)ce. Na projekt maj(cid:241) wp(cid:228)yw przyj(cid:246)ta strategia oraz grupa odbiorców, jak równie(cid:276) zasoby biznesowe planowane do udost(cid:246)pnienia. Oczywi(cid:264)cie dla projektu znaczenie ma te(cid:276) wybrana metoda technologiczna. W tym rozdziale skon- centrowano si(cid:246) na nast(cid:246)puj(cid:241)cych trzech obszarach: (cid:120) projektowanie interfejsu API dla ró(cid:276)nych grup odbiorców; (cid:120) zapewnienie przegl(cid:241)du kwestii technologicznych; (cid:120) wyró(cid:276)nienie ogólnych zagadnie(cid:254) projektowych. Strategia dotycz(cid:241)ca interfejsów API skupia si(cid:246) g(cid:228)ównie na utworzeniu co najmniej jednego kana(cid:228)u z interfejsem API w celu u(cid:228)atwienia osi(cid:241)gni(cid:246)cia przyj(cid:246)tych celów biznesowych. Gdy ludzie korzystaj(cid:241) z interfejsu API, tak naprawd(cid:246) nie zastanawiaj(cid:241) si(cid:246) nad warto(cid:264)ci(cid:241) jego samego. Zainteresowani s(cid:241) warto(cid:264)ci(cid:241), jak(cid:241) uzyskaj(cid:241) za po(cid:264)rednictwem interfejsu, czyli zasobami biznesowymi (produktami i us(cid:228)ugami) udost(cid:246)pnianymi za jego pomoc(cid:241). Przy projektowaniu interfejsów API próbujemy udost(cid:246)pni(cid:232) zasoby bizne- sowe projektantom, tak aby mogli tworzy(cid:232) aplikacje zapewniaj(cid:241)ce warto(cid:264)ci u(cid:276)ytkownikom ko(cid:254)cowym, którzy nast(cid:246)pnie b(cid:246)d(cid:241) mieli mo(cid:276)liwo(cid:264)(cid:232) uzy- skania okre(cid:264)lonego rodzaju warto(cid:264)ci pozwalaj(cid:241)cej zako(cid:254)czy(cid:232) cykl korzy(cid:264)ci zwi(cid:241)zanych z interfejsem API. 81 Kup książkęPoleć książkę Ogólnie rzecz bior(cid:241)c, najlepsze interfejsy API s(cid:241) starannie zaprojektowane, (cid:228)atwe do opanowania, z logiczn(cid:241) struktur(cid:241) i wewn(cid:246)trznie spójne. Dzi(cid:246)ki temu projektanci mog(cid:241) stwierdzi(cid:232), jak ze wzgl(cid:246)dnym powodzeniem wyeli- minowa(cid:232) wszelkie niejasno(cid:264)ci. Interfejs API powinien by(cid:232) troch(cid:246) jak samo- chód. Ka(cid:276)de auto wyposa(cid:276)one jest w kierownic(cid:246) oraz peda(cid:228)y hamulca i gazu. Mo(cid:276)esz uzna(cid:232), (cid:276)e (cid:264)wiat(cid:228)a awaryjne, otwieranie baga(cid:276)nika lub radio s(cid:241) tro- ch(cid:246) inne w ró(cid:276)nych modelach samochodów, ale do rzadko(cid:264)ci nale(cid:276)y sytu- acja, w której do(cid:264)wiadczony kierowca nie wie, jak prowadzi(cid:232) wypo(cid:276)yczony pojazd. Projektowanie interfejsów API dla konkretnych grup odbiorców Jak w przypadku dowolnej kampanii o charakterze biznesowym interfejs API wymaga zdefiniowania grupy odbiorców. Okazuje si(cid:246), (cid:276)e w odniesie- niu do interfejsów API nale(cid:276)y rozwa(cid:276)y(cid:232) dwie podstawowe grupy. Projektanci (lub nawet szerzej rzecz ujmuj(cid:241)c, zespo(cid:228)y techniczne i tworz(cid:241)- ce produkty) to bezpo(cid:264)rednia grupa odbiorców, która korzysta z interfejsu API i buduje na jego bazie aplikacje. U(cid:276)ytkownicy ko(cid:254)cowi to po(cid:264)rednia grupa odbiorców, która stosuje aplikacje utworzone za pomoc(cid:241) interfejsu API. Aby okre(cid:264)li(cid:232) grup(cid:246) odbiorców, nale(cid:276)y si(cid:246) najpierw zastanowi(cid:232) nad sfor- mu(cid:228)owaniem wizji dotycz(cid:241)cej interfejsu API. Pozwoli to stwierdzi(cid:232), co jest celem interfejsu. W dalszej kolejno(cid:264)ci mo(cid:276)na ustali(cid:232), którzy odbiorcy spo- (cid:264)ród tych ich typów skorzystaj(cid:241) z interfejsu API oraz jak musi wygl(cid:241)da(cid:232) model interakcji. Czy interfejs jest projektowany dla dzia(cid:228)ów, które bazuj(cid:241) na informacjach z systemu ERP? Czy mo(cid:276)e interfejs ma by(cid:232) przeznaczony dla projektantów aplikacji dla urz(cid:241)dze(cid:254) przeno(cid:264)nych, najwa(cid:276)niejszych 10 part- nerów firmy, czy sprzedawców stowarzyszonych z firm(cid:241)? Przeprowad(cid:274) analiz(cid:246) segmentacji u(cid:276)ytkowników ko(cid:254)cowych i (lub) pro- jektantów oraz ustal priorytety dla segmentów. Je(cid:264)li pocz(cid:241)tkowa odpowied(cid:274) wskazuje na wszystkich jako odbiorców, sugerujemy troch(cid:246) staranniejsze przemy(cid:264)lenie tej kwestii, przynajmniej w przypadku okre(cid:264)lania priorytetów. Wyzwaniem jest projektowanie zarówno z my(cid:264)l(cid:241) o projektantach tworz(cid:241)- cych interfejs API, jak i u(cid:276)ytkownikach ko(cid:254)cowych, którzy b(cid:246)d(cid:241) stosowa(cid:232) interfejs API. Zajmiemy si(cid:246) teraz przybli(cid:276)eniem obu zagadnie(cid:254). 82 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Projektowanie pod k(cid:233)tem projektantów Projektantów mo(cid:276)na podzieli(cid:232) na wiele typów i podkategorii. Interfejs API mo(cid:276)e by(cid:232) tworzony z my(cid:264)l(cid:241) o nielicznej, bardzo specyficznej grupie pro- jektantów o wysokich kompetencjach u(cid:276)ywaj(cid:241)cych konkretnej technologii lub dla ka(cid:276)dego na (cid:264)wiecie, komu firma chcia(cid:228)aby zapewni(cid:232) dost(cid:246)p do swoich zasobów biznesowych. W zwi(cid:241)zku z tym warto zaznajomi(cid:232) si(cid:246) z segmentacj(cid:241) kategorii projektantów. Dzi(cid:246)ki temu wybór platformy tech- nicznej stanie si(cid:246) bardziej oczywisty. Inaczej mówi(cid:241)c, zespo(cid:228)y buduj(cid:241)ce interfejsy API b(cid:246)d(cid:241) zwykle zmuszone do dokonywania wielu wyborów dotycz(cid:241)cych technologii. Protokó(cid:228) SOAP czy REST? Format XML czy JSON? Protokó(cid:228) OAuth czy co(cid:264) innego? Od- powiedzi na te pytania b(cid:246)d(cid:241) bardziej ni(cid:276) cokolwiek innego zale(cid:276)ne od odbior- ców, którzy skorzystaj(cid:241) z interfejsu API. Prezentujemy jednak kilka reko- mendacji. Nasze rekomendacje technologiczne dla interfejsów API Je(cid:264)li nie ma (cid:276)adnych konkretnych powodów, aby post(cid:241)pi(cid:232) inaczej, oto pierwsze mo(cid:276)liwo(cid:264)ci, jakie powinny zosta(cid:232) obecnie wybrane przez do- wolny zespó(cid:228) tworz(cid:241)cy interfejs API: (cid:120) „Pragmatyczna” us(cid:228)uga REST na potrzeby struktury, poniewa(cid:276) u(cid:228)atwia opanowanie, wykorzystanie i rozszerzenie interfejsu API w wi(cid:246)kszym stopniu ni(cid:276) inne technologie, takie jak SOAP (w dalszej cz(cid:246)(cid:264)ci ksi(cid:241)(cid:276)ki zostanie omówiona us(cid:228)uga REST i jej „pragmatyczny” wariant). (cid:120) JSON jako format danych pobieranych i zwracanych przez interfejs API, gdy(cid:276) upraszcza programistom generowanie danych i korzystanie z nich. (cid:120) Protokó(cid:228) OAuth do zabezpieczania, poniewa(cid:276) zapobiega propagacji hase(cid:228) w internecie, a jednocze(cid:264)nie obs(cid:228)uguje ró(cid:276)ne metody uwierzy- telniania u(cid:276)ytkownika ko(cid:254)cowego. Je(cid:264)li te technologie nie s(cid:241) Ci jeszcze znane, nie przejmuj si(cid:246). W dalszej cz(cid:246)(cid:264)ci rozdzia(cid:228)u zajmiemy si(cid:246) us(cid:228)ug(cid:241) REST i formatem JSON, a protokó(cid:228) OAuth wraz z innymi zagadnieniami zwi(cid:241)zanymi z zabezpieczeniami zostanie omówiony w rozdziale 6. Co wi(cid:246)cej, opisujemy te technologie jako pierwsz(cid:241) opcj(cid:246) wyboru, a nie ja- ko jedyn(cid:241). Nowoczesne serwery aplikacji i platformy z interfejsem API umo(cid:276)liwiaj(cid:241) obs(cid:228)ugiwanie wi(cid:246)cej ni(cid:276) jednej takiej technologii. Na przyk(cid:228)ad Projektowanie interfejsów API dla konkretnych grup odbiorców (cid:95) 83 Kup książkęPoleć książkę zapewniaj(cid:241) one interfejs API, który wspiera technologie XML i JSON, albo udost(cid:246)pniaj(cid:241) interfejsy API protoko(cid:228)u SOAP i us(cid:228)ugi REST. Najlepsze procedury techniczne zwi(cid:233)zane z interfejsem API firmy Tumblr Czy chcia(cid:228)by(cid:264) si(cid:246) podzieli(cid:232) jakimikolwiek najlepszymi procedurami technicznymi zwi(cid:241)zanymi z interfejsem API firmy Tumblr? Zale(cid:276)y nam na tym, aby interfejs API by(cid:228) (cid:228)atwy do opanowania bez u(cid:276)y- cia dokumentacji. Dzi(cid:246)ki temu, jak zosta(cid:228)y zaprojektowane stosowane przez nas identyfikatory URI, powinno by(cid:232) po prostu mo(cid:276)liwe przej(cid:264)cie do poziomu wiersza polece(cid:254). Staramy si(cid:246) tylko w nieznacznym stopniu modyfikowa(cid:232) interfejs API. Jedn(cid:241) z wielkich ironii losu zwi(cid:241)zanych z witryn(cid:241) internetow(cid:241) jest to, (cid:276)e mog(cid:246) wprowadzi(cid:232) w niej zmiany w dowolnym (cid:276)(cid:241)danym momencie, a z kolei interfejs API jest wyj(cid:241)tkowo delikatny w tym sensie, (cid:276)e mo(cid:276)e spowodo- wa(cid:232), i(cid:276) przestan(cid:241) dzia(cid:228)a(cid:232) aplikacje projektantów korzystaj(cid:241)cych z tego interfejsu. Kontrola wersji to trwaj(cid:241)cy proces. Derek Gottfrid, dyrektor ds. produktów w firmie Tumblr Cho(cid:232) warto zacz(cid:241)(cid:232) od technologii REST, JSON i OAuth przy rozwa(cid:276)aniu zasto- sowania interfejsu API, s(cid:241) powody, aby nie decydowa(cid:232) si(cid:246) na te rozwi(cid:241)zania. Us(cid:228)uga REST mo(cid:276)e powodowa(cid:232) mniej elastyczne interakcje mi(cid:246)dzy klien- tami a interfejsem API. Mog(cid:241) by(cid:232) dost(cid:246)pne lepsze metody osi(cid:241)gni(cid:246)cia po- dobnego wyniku, bo daj(cid:241)ce wi(cid:246)ksz(cid:241) efektywno(cid:264)(cid:232). Prostszy model obiektowy formatu JSON jest preferowany w wielu sytu- acjach w celu zmniejszenia liczby bajtów, co poprawia wydajno(cid:264)(cid:232) dostar- czania bajtów za pomoc(cid:241) protoko(cid:228)u HTTP. J(cid:246)zyk XML stwarza potencja(cid:228) u(cid:276)ycia bardziej rozbudowanych znaczników i opcji semantycznych. Ponadto w przypadku formatu XML istnieje znacznie wi(cid:246)cej standardów organizowa- nia tre(cid:264)ci ni(cid:276) dla formatu JSON. Oznacza to, (cid:276)e aplikacje analizuj(cid:241)ce oraz inne biblioteki kodu mog(cid:241) zwi(cid:246)kszy(cid:232) efektywno(cid:264)(cid:232) projektowania aplikacji. Cho(cid:232) protokó(cid:228) OAuth znakomicie nadaje si(cid:246) do zabezpieczania transakcji interfejsu API, najlepiej dostosowany jest do potrzeb du(cid:276)ych grup nieznanych projektantów, którzy próbuj(cid:241) u(cid:276)y(cid:232) interfejsu API firmy. Je(cid:264)li odbiorcy doce- lowi to niewielka grupa projektantów firmy, protokó(cid:228) OAuth mo(cid:276)e okaza(cid:232) si(cid:246) przesad(cid:241). 84 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Kluczem do podj(cid:246)cia takich decyzji jest zrozumienie tego, kto b(cid:246)dzie ko- rzysta(cid:232) z interfejsu API, a tak(cid:276)e tego, w jaki sposób takie osoby b(cid:246)d(cid:241) tworzy(cid:232) aplikacje interesuj(cid:241)ce dla u(cid:276)ytkowników ko(cid:254)cowych. Projektowanie pod k(cid:233)tem u(cid:348)ytkowników aplikacji Im lepiej mo(cid:276)esz zrozumie(cid:232), jaki typ dost(cid:246)pu jest wymagany przez u(cid:276)ytkow- ników ko(cid:254)cowych, tym wi(cid:246)cej informacji uzyskasz na temat tego, co ma zo- sta(cid:232) uwzgl(cid:246)dnione w interfejsie API, oraz tego, jak w najwi(cid:246)kszym stopniu u(cid:228)atwi(cid:232) dost(cid:246)p. Firmy publikuj(cid:241)ce interfejsy API powinny si(cid:246) zastanowi(cid:232), czego u(cid:276)ytkownicy oczekuj(cid:241) od ich zasobów biznesowych i jak mog(cid:241) zapew- ni(cid:232) dost(cid:246)p, który spowoduje zwi(cid:246)kszenie wykorzystania interfejsu API. Trudno w tym przypadku o generalizowanie, poniewa(cid:276) cz(cid:246)sto nie jest oczy- wiste, jakiego rodzaju aplikacje b(cid:246)d(cid:241) tworzone. Poza tym mo(cid:276)esz tylko w za- rysie wyobra(cid:276)a(cid:232) sobie skrywane potrzeby u(cid:276)ytkowników ko(cid:254)cowych do- tycz(cid:241)ce zasobów biznesowych. Co wi(cid:246)cej, je(cid:264)li po udost(cid:246)pnieniu interfejsy API odnios(cid:241) sukces, zwykle b(cid:246)d(cid:241) stanowi(cid:232) inspiracj(cid:246) dla nowych pomys(cid:228)ów i zastosowa(cid:254), które by(cid:232) mo(cid:276)e nie by(cid:228)y rozwa(cid:276)ane w fazie projektowania. Dotyczy to zarówno prywatnych, jak i publicznych interfejsów API. Na przyk(cid:228)ad popularne funkcje, takie jak pobieranie z serwisu Twitter wszystkich wpisów jednej osoby (interfejs API firmy Twitter) lub tworzenie mapy z naniesionym na niej po(cid:228)o(cid:276)eniem (interfejs API serwisu Google Maps), mog(cid:241) by(cid:232) wykorzystywane z du(cid:276)(cid:241) (cid:228)atwo(cid:264)ci(cid:241), poniewa(cid:276) wiele aplikacji oferuje realizowanie tych prostych dzia(cid:228)a(cid:254). Inne, bardziej z(cid:228)o(cid:276)one funkcje zosta(cid:228)y dodane pó(cid:274)niej b(cid:241)d(cid:274) okaza(cid:228)y si(cid:246) przydatne w wyniku ci(cid:241)g(cid:228)ego powi(cid:246)kszania si(cid:246) bazy u(cid:276)ytkowników. Ko(cid:254)cowy wniosek jest taki, (cid:276)e im wi(cid:246)- cej uzyskasz informacji o populacji u(cid:276)ytkowników ko(cid:254)cowych i rodzaju wymaganych przez nich aplikacji, tym lepiej b(cid:246)dziesz poinformowany na etapie decydowania o tym, jakie funkcje maj(cid:241) zosta(cid:232) zaoferowane jako pierwsze. Najlepsze praktyki zwi(cid:233)zane z projektem interfejsów API Z do(cid:264)wiadczenia wiemy, (cid:276)e w przypadku interfejsów API cz(cid:246)(cid:264)(cid:232) rzeczy si(cid:246) udaje, a cz(cid:246)(cid:264)(cid:232) nie. W tym podrozdziale przedstawiamy kilka propozycji, które uwa(cid:276)amy za solidne i najlepsze praktyki zwi(cid:241)zane z projektem in- terfejsów API. Najlepsze praktyki zwi(cid:233)zane z projektem interfejsów API (cid:95) 85 Kup książkęPoleć książkę Organizacja NPR zna swoich odbiorców Organizacja NPR opracowa(cid:228)a swój program zwi(cid:241)zany z interfejsem API, bazuj(cid:241)c na dobrej znajomo(cid:264)ci odbiorców docelowych. Zasadniczo z da- lekowzroczno(cid:264)ci organizacji korzystaj(cid:241) nast(cid:246)puj(cid:241)ce cztery grupy: (cid:120) Pracownicy organizacji NPR to najwi(cid:246)ksza grupa u(cid:276)ywaj(cid:241)ca interfejsu API, która obs(cid:228)uguje ca(cid:228)(cid:241) infrastruktur(cid:246) serwisu NPR.org, g(cid:228)ówn(cid:241) witryn(cid:246) internetow(cid:241), a tak(cid:276)e inne zasoby cyfrowe. Pocz(cid:241)tkowo inter- fejs by(cid:228) stosowany do usprawniania systemu zarz(cid:241)dzania tre(cid:264)ci(cid:241) CMS wspieraj(cid:241)cego witryn(cid:246) internetow(cid:241). Mia(cid:228)o to na celu umo(cid:276)liwienie u(cid:276)ycia niestandardowych kana(cid:228)ów informacyjnych opracowywanych przez dzia(cid:228) redakcyjny i projektowy. Najwi(cid:246)ksz(cid:241) korzy(cid:264)ci(cid:241) wynikaj(cid:241)c(cid:241) z zasto- sowania interfejsu API by(cid:228)o utworzenie wielu aplikacji firmowanych przez organizacj(cid:246) NPR dla urz(cid:241)dze(cid:254) przeno(cid:264)nych i innych platform. W efekcie po up(cid:228)ywie nieca(cid:228)ego roku osi(cid:241)gni(cid:246)to 100-procentowy wzrost liczby wy(cid:264)wietle(cid:254) stron dla wszystkich zasobów cyfrowych. (cid:120) Stacje cz(cid:228)onkowskie organizacji NPR stanowi(cid:241) istotne grono odbiorców. U(cid:276)ywaj(cid:241) one interfejsu API do pobierania tre(cid:264)ci i tworzenia dla swoich spo(cid:228)eczno(cid:264)ci stron zespolonych z tre(cid:264)ci(cid:241) o zasi(cid:246)gu lokalnym i ogólno- krajowym. (cid:120) Interfejs API organizacji NPR stworzy(cid:228) nowe mo(cid:276)liwo(cid:264)ci dla partnerów, poniewa(cid:276) wi(cid:241)za(cid:228)y si(cid:246) z nim niskie koszty integracji. Oznacza(cid:228)o to, (cid:276)e ju(cid:276) istniej(cid:241)ce rozwi(cid:241)zania równie(cid:276) by(cid:228)y (cid:228)atwiejsze do utrzymania i roz- wijania, gdy(cid:276) kana(cid:228) komunikacji by(cid:228) bardziej niezawodny ni(cid:276) wcze(cid:264)niej, kiedy rozwi(cid:241)zania cz(cid:246)sto by(cid:228)y obs(cid:228)ugiwane za pomoc(cid:241) niestandardo- wych kana(cid:228)ów informacyjnych XML, kana(cid:228)ów RSS lub innych mniej ni(cid:276) optymalnych metod. (cid:120) Czwarta grupa korzystaj(cid:241)ca z interfejsu API organizacji NPR to ogó(cid:228) spo(cid:228)e- cze(cid:254)stwa. Rozszerzenie interfejsu u(cid:228)atwi(cid:228)o wsparcie misji organizacji NPR, która oferuje us(cid:228)ug(cid:246) publiczn(cid:241), a ponadto zapewni(cid:228)o zestaw widgetów i narz(cid:246)dzi wspomagaj(cid:241)cych tworzenie zewn(cid:246)trznych witryn interne- towych wykorzystuj(cid:241)cych tre(cid:264)(cid:232) tej organizacji w innowacyjny sposób. Odró(cid:348)nij w(cid:293)asny interfejs API Podstawowa sprawa: dlaczego projektant powinien u(cid:276)y(cid:232) Twojego interfej- su API? Czym si(cid:246) on ró(cid:276)ni od innych rozwi(cid:241)za(cid:254)? Dlaczego nale(cid:276)a(cid:228)oby z niego skorzysta(cid:232)? 86 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Oto kilka mo(cid:276)liwych sposobów odró(cid:276)nienia w(cid:228)asnego interfejsu API: (cid:120) Dane s(cid:241) unikalne, bardziej kompletne lub dok(cid:228)adniejsze ni(cid:276) w przy- padku interfejsu konkurencji. (cid:120) Oferowane jest lepsze wsparcie b(cid:241)d(cid:274) (cid:228)atwiejszy proces rejestrowania. (cid:120) Interfejs API jest solidniejszy, bardziej niezawodny, ciekawszy albo szybszy ni(cid:276) rozwi(cid:241)zanie alternatywne. (cid:120) Zaproponowane warunki s(cid:241) atrakcyjniejsze dla projektantów. By(cid:232) mo- (cid:276)e oferujesz wi(cid:246)kszy darmowy ruch sieciowy zwi(cid:241)zany z danymi lub lepsze stawki. Zaakcentuj to, dlaczego kto(cid:264) powinien u(cid:276)ywa(cid:232) Twojego interfejsu API, a nie innego rozwi(cid:241)zania. Mo(cid:276)e nim by(cid:232) publiczny interfejs API konkurencji, alternatywne (cid:274)ród(cid:228)o danych lub starsza (i bardziej znajoma) metoda po- wi(cid:241)zana z prywatnym interfejsem API. Mo(cid:276)liwe jest te(cid:276) rozró(cid:276)nienie ofert i elementów motywacyjnych zwi(cid:241)zanych z Twoim interfejsem API. Jedna ze strategii polega na zaoferowaniu ró(cid:276)nych wariantów cenowych zale(cid:276)nych od skali b(cid:241)d(cid:274) typu wykorzystania. Taka strategia umo(cid:276)liwia pozyskanie wi(cid:246)kszej liczby poziomów subskrybentów interfejsu. Cz(cid:246)(cid:264)(cid:232) wywo(cid:228)a(cid:254) in- terfejsu API mo(cid:276)e by(cid:232) bezp(cid:228)atna, a cz(cid:246)(cid:264)(cid:232) mo(cid:276)e wymaga(cid:232) dokonania p(cid:228)at- no(cid:264)ci. Mo(cid:276)esz zezwoli(cid:232) na darmowe u(cid:276)ycie interfejsu w przypadku pu- blicznej aplikacji, natomiast pobiera(cid:232) op(cid:228)at(cid:246), gdy wykorzystywany jest on wewn(cid:241)trz firmy. Zapewnij (cid:293)atwo(cid:316)(cid:235) testowania i u(cid:348)ywania interfejsu API Je(cid:264)li Twój interfejs API jest jedn(cid:241) z wielu opcji, jego potencjalni u(cid:276)ytkownicy mog(cid:241) po(cid:264)wi(cid:246)ci(cid:232) na jego wypróbowanie tylko kilka minut. Je(cid:276)eli nie mog(cid:241) stwierdzi(cid:232) prawie natychmiastowych post(cid:246)pów, zainteresuj(cid:241) si(cid:246) czym(cid:264) in- nym. W przypadku udanych programów zwi(cid:241)zanych z interfejsami API eliminowane s(cid:241) wszystkie bariery odnosz(cid:241)ce si(cid:246) do u(cid:276)ytkowania. Istnieje kilka metod, które to umo(cid:276)liwiaj(cid:241). W odniesieniu do prywatnych interfejsów API wa(cid:276)ne jest zademonstrowanie prawdziwej warto(cid:264)ci wynikaj(cid:241)cej z uruchomienia systemu lub aplikacji na bazie interfejsu API. Na przyk(cid:228)ad interfejs mo(cid:276)e oferowa(cid:232) znacznie bar- dziej elastyczny dost(cid:246)p do tre(cid:264)ci, lepsz(cid:241) ogóln(cid:241) wydajno(cid:264)(cid:232), efektywniejsze cykle projektowania albo inn(cid:241) korzy(cid:264)(cid:232). Aby przyspieszy(cid:232) proces adaptacji interfejsu API, zidentyfikuj konkretny przypadek u(cid:276)ycia znacz(cid:241)cej aplikacji i zadbaj o uwzgl(cid:246)dnienie go w (cid:264)rodowisku produkcyjnym. Gdy to nast(cid:241)pi, mo(cid:276)liwe b(cid:246)dzie dostrojenie tego przypadku zastosowania i zaprezentowania Najlepsze praktyki zwi(cid:233)zane z projektem interfejsów API (cid:95) 87 Kup książkęPoleć książkę jego warto(cid:264)ci. Po wdro(cid:276)eniu mo(cid:276)liwego do zademonstrowania przypadku u(cid:276)ycia (cid:228)atwiejsze b(cid:246)dzie wskazanie go jako przyk(cid:228)adu, który mo(cid:276)e zosta(cid:232) wykorzystany przez innych. Ponadto projektanci, którzy zaimplementowali ten pierwszy przypadek u(cid:276)ycia, u(cid:228)atwi(cid:241) proces promowania, pod warun- kiem (cid:276)e ich do(cid:264)wiadczenie z nim zwi(cid:241)zane jest pozytywne. Nie zapomnij postara(cid:232) si(cid:246) o poparcie odpowiednich osób z zarz(cid:241)du i (lub) zespo(cid:228)ów za- rz(cid:241)dzaj(cid:241)cych, aby usprawni(cid:232) sobie dalsze dzia(cid:228)ania. W przypadku publicznych interfejsów API jedn(cid:241) z metod post(cid:246)powania jest oferowanie okre(cid:264)lonego poziomu darmowego dost(cid:246)pu. Wielu projektantów nawet nie rozwa(cid:276)y u(cid:276)ycia interfejsu, je(cid:264)li b(cid:246)dzie on zapewnia(cid:232) tylko p(cid:228)at- ne opcje. Na tym etapie cyklu pozyskiwania klientów projektant mo(cid:276)e nie wiedzie(cid:232), czy Twój interfejs spe(cid:228)nia jego wymagania lub czy model bizne- sowy jego aplikacji b(cid:246)dzie uwzgl(cid:246)dnia(cid:232) p(cid:228)atny dost(cid:246)p. Programy, które odnios(cid:228)y sukces, sprawiaj(cid:241) te(cid:276), (cid:276)e testowanie interfejsu API jest wyj(cid:241)tkowo proste i szybkie. Gdy to tylko mo(cid:276)liwe, zapewniaj(cid:241) one natychmiastow(cid:241) satysfakcj(cid:246). Projektantom wy(cid:264)wietlaj(cid:241)cym interfejs API serwisu Twitter prezentowana jest konsola, która pozwala na b(cid:228)yskawiczne testowanie. Firma Twitter idzie o krok dalej, oferuj(cid:241)c operacje interfejsu, które nie wymagaj(cid:241) (cid:276)adnego rejestrowania ani uwierzytelniania (jest to na przyk(cid:228)ad operacja powi(cid:241)zana z publiczn(cid:241) osi(cid:241) czasu, umo(cid:276)liwiaj(cid:241)ca pro- jektantom uzyskanie dost(cid:246)pu do ostatnich aktualizacji statusu dla wszyst- kich publicznych u(cid:276)ytkowników na ca(cid:228)ym (cid:264)wiecie). Je(cid:264)li warunkiem zastosowania interfejsu API jest rejestracja, udoskonal proces. Nie jest dobrym pomys(cid:228)em zadawanie wi(cid:246)cej ni(cid:276) kilku pyta(cid:254) kwalifikuj(cid:241)- cych lub implementowanie procesu zatwierdzania, w ramach którego musisz skontaktowa(cid:232) si(cid:246) z projektantem. Zanim to nast(cid:241)pi, projektant mo(cid:276)e ju(cid:276) straci(cid:232) zainteresowanie interfejsem API. Inaczej sytuacja wygl(cid:241)da w przypadku prywatnych interfejsów API, dla któ- rych niezb(cid:246)dna jest oficjalna umowa partnerska. Im wi(cid:246)cej informacji mo- (cid:276)esz zapewni(cid:232) w celu zach(cid:246)cenia partnerów do zarejestrowania, tym lepiej. Zapewnij (cid:293)atwo(cid:316)(cid:235) zrozumienia interfejsu API Najbardziej udane interfejsy API s(cid:241) projektowane intuicyjnie. Prostota jest kluczem, pewnikiem dotycz(cid:241)cym nie tylko tego, na co interfejs pozwala, ale te(cid:276) sposobów prezentowania funkcji projektantom. Znakomitym przy- k(cid:228)adem jest interfejs API us(cid:228)ugi Facebook Graph. Opis tego interfejsu czyta si(cid:246) jak ksi(cid:241)(cid:276)k(cid:246). Aby zrozumie(cid:232), jakie s(cid:241) jego mo(cid:276)liwo(cid:264)ci, niezb(cid:246)dna jest bardzo ograniczona dokumentacja. 88 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Stare powiedzenie dotycz(cid:241)ce projektów, które odnosi si(cid:246) te(cid:276) do interfej- sów API, brzmi: „Spraw, aby interfejs by(cid:228) tak prosty, jak to mo(cid:276)liwe, lecz nie zbyt prosty”. Twórcy publikuj(cid:241)cy interfejsy API cz(cid:246)sto do(cid:228)(cid:241)czaj(cid:241) za wiele funkcji lub takie funkcje, które tak naprawd(cid:246) s(cid:241) nieodpowiednie. Na przyk(cid:228)ad mieli(cid:264)my do czynienia z publicznymi interfejsami API zawieraj(cid:241)- cymi funkcje, które przeznaczone by(cid:228)y wy(cid:228)(cid:241)cznie do u(cid:276)ytku wewn(cid:246)trznego (takie jak tabele kodów wewn(cid:246)trznych). Kin Lane, promotor projektantów w firmie Mimeo, twierdzi, (cid:276)e mniejsza liczba funkcji b(cid:246)dzie korzystna dla projektu interfejsu API. „Moja rada jest nast(cid:246)puj(cid:241)ca: prostsze znaczy lepsze. Us(cid:228)uga REST, format JSON czy inne proste i zrozumia(cid:228)e us(cid:228)ugi. Nie próbujcie zbytnio komplikowa(cid:232) interfejsu. Skoncentrujcie si(cid:246) na podstawowych komponentach tworz(cid:241)cych interfejs API. Zróbcie jedno, ale naprawd(cid:246) dobrze, a ponadto do(cid:228)(cid:241)czcie do tego prost(cid:241) dokumentacj(cid:246) i przyk(cid:228)adowe kody. S(cid:241) to fundamenty interfejsu API”. Oprócz oferowania najmniejszego, ale jednocze(cid:264)nie w miar(cid:246) mo(cid:276)liwo(cid:264)ci najbardziej rozbudowanego zestawu operacji kluczowe znaczenie ma te(cid:276) okre(cid:264)lenie struktury interfejsu API w przyst(cid:246)pny sposób. Jest to ogromna za- leta interfejsów API, które zgodne s(cid:241) z opisanymi dalej wzorcami „pragma- tycznej” us(cid:228)ugi REST. Tego rodzaju interfejsy API s(cid:241) (cid:228)atwe do opanowania, poniewa(cid:276) prezentuj(cid:241) swoje operacje w postaci zrozumia(cid:228)ych dla cz(cid:228)owieka identyfikatorów URI, które mog(cid:241) by(cid:232) testowane za pomoc(cid:241) prostych narz(cid:246)- dzi, takich jak przegl(cid:241)darka internetowa. Mo(cid:276)e si(cid:246) wydawa(cid:232), (cid:276)e podczas tworzenia interfejsu API nieistotne jest to, aby cechowa(cid:228) si(cid:246) on intuicyjno(cid:264)ci(cid:241), (cid:228)atwo(cid:264)ci(cid:241) obs(cid:228)ugi i elegancj(cid:241). Je(cid:264)li interfejs API zapewnia odpowiedni(cid:241) funkcjonalno(cid:264)(cid:232), to czy projektanci i tak nie b(cid:246)d(cid:241) z niej korzysta(cid:232)? Mo(cid:276)e to mie(cid:232) sens do momentu pojawienia si(cid:246) konkurencji dla interfejsu. Twórcy aplikacji s(cid:241) wybredni, zadufani w sobie, a przede wszystkim dzia(cid:228)aj(cid:241) w po(cid:264)piechu. Elegancko zaprojektowany interfejs API, którego obs(cid:228)uga sprawi przyjemno(cid:264)(cid:232) projektantom, zyska zwolenników i za- dowolonych u(cid:276)ytkowników w stopniu, na jaki nie pozwol(cid:241) dzia(cid:228)ania cechuj(cid:241)- ce si(cid:246) mniejsz(cid:241) staranno(cid:264)ci(cid:241). Nie rób niczego dziwnego Wyró(cid:276)ni(cid:232) mo(cid:276)na tak(cid:276)e inne aspekty prostoty, które mog(cid:241) przyczyni(cid:232) si(cid:246) do u(cid:228)atwienia adaptacji Twojego interfejsu API. Jednym z czynników powo- dzenia jest uczestniczenie w spotkaniach, które mog(cid:241) by(cid:232) ju(cid:276) znane projek- tantom. Najlepsze praktyki zwi(cid:233)zane z projektem interfejsów API (cid:95) 89 Kup książkęPoleć książkę Jest to szczególnie wa(cid:276)ne w bran(cid:276)y zabezpiecze(cid:254). Wiele interfejsów API oferuje niestandardowe lub z(cid:228)o(cid:276)one schematy zabezpiecze(cid:254), które wymagaj(cid:241) od projektantów opanowania ich od podstaw, co jest znaczn(cid:241) przeszkod(cid:241) na drodze do decyzji o adaptacji interfejsu. Zastanów si(cid:246) nad u(cid:276)yciem powszechnych standardów, takich jak protokó(cid:228) OAuth b(cid:241)d(cid:274) innych ogólnie znanych schematów zabezpiecze(cid:254). Dzi(cid:246)ki temu nie tylko mo(cid:276)esz zwi(cid:246)k- szy(cid:232) szanse adaptacji interfejsu, ale te(cid:276) zmniejszy(cid:232) w(cid:228)asny (oraz projektantów) nak(cid:228)ad pracy zwi(cid:241)zany z projektowaniem. Mniej znaczy wi(cid:253)cej Udane interfejsy API cz(cid:246)sto na pocz(cid:241)tku zapewniaj(cid:241) absolutnie minimaln(cid:241) liczb(cid:246) funkcji, a pó(cid:274)niej z up(cid:228)ywem czasu i po uzyskaniu opinii stopniowo dodawane s(cid:241) kolejne. Po pierwsze, gdy ju(cid:276) udost(cid:246)pniono interfejs API, nie ma odwrotu. Oznacza to, (cid:276)e po opublikowaniu funkcjonalno(cid:264)ci i zbudowaniu na ich bazie aplikacji przez projektantów bardzo, ale to bardzo trudno wycofa(cid:232) takie funkcje. W przypadku witryny internetowej wymagane jest jedynie ukrycie funkcji. Ograniczenie funkcjonalno(cid:264)ci interfejsu API wi(cid:241)(cid:276)e si(cid:246) z niemi(cid:228)(cid:241) decyzj(cid:241) o dal- szym wspieraniu funkcji do momentu, a(cid:276) kworum projektantów zacznie u(cid:276)ywa(cid:232) nast(cid:246)pnej ulepszonej wersji tej funkcji lub jej iteracji. Mo(cid:276)e to rów- nie(cid:276) spowodowa(cid:232) ryzyko problemów z aplikacjami projektantów i wyni- kaj(cid:241)cego z tego ich gniewu. Po drugie, ca(cid:228)kiem prawdopodobne jest to, (cid:276)e klienci b(cid:246)d(cid:241) si(cid:246) domaga(cid:232) zmiany rozwoju interfejsu API w innych kierunkach, ni(cid:276) wcze(cid:264)niej sobie w ogóle wyobra(cid:276)ano. Dotyczy to zw(cid:228)aszcza prywatnych interfejsów API, w przypad- ku których wewn(cid:246)trzne zespo(cid:228)y projektantów maj(cid:241) bli(cid:276)sze relacje z dostawc(cid:241) interfejsów API, a tak(cid:276)e wi(cid:246)kszy wp(cid:228)yw. O czym(cid:264) takim nieustannie si(cid:246) dowiadujemy. Niezale(cid:276)nie od tego, czy chodzi o strategi(cid:246), typ projektanta, rodzaj aplikacji, czy o konkretn(cid:241) funkcj(cid:246), która okazuje si(cid:246) warto(cid:264)ciowa, inter- fejs API cz(cid:246)sto rozwija si(cid:246) w innym kierunku, ni(cid:276) przewidywano. W takiej sytuacji rozpocz(cid:246)cie od minimalnego poziomu funkcji mo(cid:276)e da(cid:232) mo(cid:276)liwo(cid:264)(cid:232) najbardziej przejrzystego i najszybszego rozwoju produktu. Prawdopodobnie istnieje wi(cid:246)cej powodów ni(cid:276) podane, ale ogólnie rzecz bio- r(cid:241)c, prawie zawsze dobrym rozwi(cid:241)zaniem b(cid:246)dzie rozpocz(cid:246)cie od mniejszej liczby funkcji i dodawanie kolejnych w razie potrzeby. Jest to zgodne z za- sad(cid:241), która g(cid:228)osi, (cid:276)e mniej znaczy wi(cid:246)cej. 90 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Ukierunkowanie na konkretny segment projektantów Przed zastanowieniem si(cid:246) nad sposobem uruchomienia interfejsu API pomy(cid:264)l o tym, kto ma by(cid:232) jego odbiorc(cid:241) i jakie dzia(cid:228)anie ma zosta(cid:232) przez niego podj(cid:246)te. Jak w przypadku wszystkich dobrych programów marketingowych kam- pania marketingowa zwi(cid:241)zana z interfejsem API mo(cid:276)e by(cid:232) znacznie u(cid:228)a- twiona przez ustalenie konkretnego segmentu projektantów lub aplikacji, które maj(cid:241) zosta(cid:232) uwzgl(cid:246)dnione. Upro(cid:264)ci to doprecyzowanie strategii, taktyki, zasobów i metody pomiaru skali powodzenia. Kontaktuj(cid:241)c si(cid:246) z firmami w trakcie uruchamiania interfejsu API, cz(cid:246)sto zada- jemy nast(cid:246)puj(cid:241)ce pytanie: „Kim s(cid:241) odbiorcy docelowi?”. Je(cid:264)li w odpowiedzi us(cid:228)yszymy, (cid:276)e wszyscy, b(cid:246)dziemy zmartwieni. Podobnie je(cid:264)li zadamy py- tanie: „Jakiego rodzaju aplikacje maj(cid:241) zosta(cid:232) zbudowane?”, b(cid:246)dziemy zasmu- ceni po us(cid:228)yszeniu, (cid:276)e chodzi o wszystkie rodzaje. Z czego to wynika? Tak naprawd(cid:246) trudno stworzy(cid:232) interfejs API, który spe(cid:228)ni wymagania ka(cid:276)dego mo(cid:276)liwego elementu oraz przypadku u(cid:276)ycia. Je(cid:264)li nawet otrzymano by idealny interfejs API, nie jest mo(cid:276)liwy skuteczny marke- ting dla tych wszystkich segmentów. Po cz(cid:246)(cid:264)ci atrakcyjno(cid:264)(cid:232) interfejsu API, prywatnego lub publicznego, polega na tym, (cid:276)e umo(cid:276)liwia on projektantom wprowadzanie innowacji w sposób, jakiego dostawca interfejsu mo(cid:276)e nie przewidzie(cid:232). Oznacza to, (cid:276)e podczas uruchamiania interfejsu wa(cid:276)ne jest okre(cid:264)lenie oczekiwa(cid:254) odno(cid:264)nie do tego, jak us(cid:228)uga b(cid:246)dzie prawdopodobnie u(cid:276)ywana. Dzi(cid:246)ki temu mo(cid:276)liwe b(cid:246)dzie zapewnienie interfejsu API, który spe(cid:228)ni wymagania dotycz(cid:241)ce przypad- ków u(cid:276)ycia. Dla ka(cid:276)dego z nich ustal, jacy prawdopodobnie b(cid:246)d(cid:241) odbiorcy docelowi, a nast(cid:246)pnie projektuj pod ich k(cid:241)tem. Po odniesieniu sukcesu w przypadku pierwszego segmentu mo(cid:276)esz doda(cid:232) nowych partnerów, którzy z kolei umo(cid:276)liwi(cid:241) rozszerzenie projektu o wspar- cie ich konkretnych potrzeb. Je(cid:264)li uruchamiany jest publiczny interfejs API, przeprowad(cid:274) analizy dotycz(cid:241)ce demografii segmentów projektantów we- d(cid:228)ug j(cid:246)zyka lub typu platformy aplikacji. Kwestie techniczne projektu interfejsów API W tym podrozdziale opisano kwestie projektowe natury filozoficznej i tech- nicznej, które w du(cid:276)ym stopniu wp(cid:228)ywaj(cid:241) na sposób funkcjonowania in- terfejsu API. Kwestie techniczne projektu interfejsów API (cid:95) 91 Kup książkęPoleć książkę Us(cid:293)uga REST Ró(cid:276)ne warianty us(cid:228)ugi REST (Representational State Transfer) to obecnie pre- ferowana metoda tworzenia interfejsów API. Styl bazuj(cid:241)cy na tej us(cid:228)udze zo- sta(cid:228) opracowany w ramach pracy doktorskiej przez Roya Fieldinga, który by(cid:228) jednym z twórców protoko(cid:228)u HTTP. Zasadniczo Fielding zaproponowa(cid:228) u(cid:276)ycie tego protoko(cid:228)u do komunikacji mi(cid:246)dzy komputerami. W konsekwencji us(cid:228)uga REST oparta jest na standar- dzie HTTP. Korzystaj(cid:241)c ze sk(cid:228)adników protoko(cid:228)u HTTP, us(cid:228)uga dzieli prze- strze(cid:254) nazw na zestaw „zasobów” opartych na unikalnych wzorcach identyfikatorów URI. Ponadto us(cid:228)uga REST stosuje standardowe metody protoko(cid:228)u HTTP (GET, POST, PUT i DELETE) do odwzorowywania operacji na bazie tych „zasobów”. Te standardowe metody dokonuj(cid:241) odwzorowania na funkcje create (utwórz), read (odczytaj), update (aktualizuj) i delete (usu(cid:254)), które s(cid:241) znane generacjom programistów w postaci skrótu CRUD. Identyfikatory URI i adresy URL: czym si(cid:253) ró(cid:348)ni(cid:233)? W (cid:264)wiecie standardów internetowych identyfikator URI (Uniform Resource Identifier) to ogólne odwo(cid:228)anie do „zasobu” dost(cid:246)pnego w sieci. Mo(cid:276)e to by(cid:232) bardzo konkretne odwo(cid:228)anie opisuj(cid:241)ce protokó(cid:228) sieciowy, który ma zosta(cid:232) u(cid:276)yty do uzyskania dost(cid:246)pu do odwo(cid:228)ania w sieci, metod(cid:246) zapew- niaj(cid:241)c(cid:241) ten dost(cid:246)p oraz miejsce, w którym odwo(cid:228)anie ma by(cid:232) szukane. Na przyk(cid:228)ad http://helion.pl/ksiazki/autocad-2014-pl-andrzej-pikon,ac23pl.htm to identyfikator URI. Identyfikator mo(cid:276)e by(cid:232) te(cid:276) znacznie ogólniejszy. Jeden z jego podzbiorów jest identyfikowany przez skrót URN (Uniform Resource Name), który po prostu identyfikuje unikalny identyfikator obiektu. W historii internetu termin adresu URL (Uniform Resource Locator) cz(cid:246)sto by(cid:228) u(cid:276)ywany do odwo(cid:228)ywania si(cid:246) do typu identyfikatora URI, który obej- muje protokó(cid:228) sieciowy. Z technicznego punktu widzenia takie zastosowanie jest poprawne, ale w (cid:264)wiecie standardów internetowych mia(cid:228)o miejsce stopniowe przechodzenie do wykorzystywania skrótu URI w przypadku takich odwo(cid:228)a(cid:254). W niniejszej ksi(cid:241)(cid:276)ce b(cid:246)dziemy si(cid:246) trzyma(cid:232) takiej definicji i konsekwentnie u(cid:276)ywa(cid:232) terminu URI. W us(cid:228)udze REST identyfikator URI w unikalny sposób odwo(cid:228)uje si(cid:246) do za- sobu, obiektu lub kolekcji obiektów. Fielding sformalizowa(cid:228) t(cid:246) struktur(cid:246) i zapewni(cid:228) j(cid:241) w postaci prostej metody projektowania interfejsu API, który b(cid:246)dzie dzia(cid:228)a(cid:232) w przypadku ka(cid:276)dego komputera b(cid:241)d(cid:274) systemu operacyj- nego. Na przyk(cid:228)ad program na komputerze A wymaga sprawdzenia listy 92 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę klientów. Dysponuje on informacj(cid:241) o istnieniu na komputerze zasobu zdefi- niowanego przez identyfikator URI, w którym mo(cid:276)e uzyska(cid:232) dost(cid:246)p do listy. Wszystkie dzia(cid:228)ania, które mog(cid:241) by(cid:232) realizowane w odniesieniu do „klienta” obiektu, takie jak usuwanie lub dodawanie, s(cid:241) dost(cid:246)pne za po(cid:264)rednictwem odsy(cid:228)aczy i reprezentowane jako dane XML (zgodnie z pierwotn(cid:241) propozycj(cid:241) Fieldinga dane XML i hipertekst s(cid:241) kluczowymi elementami us(cid:228)ugi REST). Obecnie prawie ka(cid:276)da platforma informatyczna mo(cid:276)e komunikowa(cid:232) si(cid:246) z serwerem HTTP. Najlepsze interfejsy API bazuj(cid:241)ce na us(cid:228)udze REST potrze- buj(cid:241) do dzia(cid:228)ania niewiele wi(cid:246)cej ni(cid:276) podstawowej obs(cid:228)ugi protoko(cid:228)u HTTP. Porównaj to z wcze(cid:264)niejszymi rozwi(cid:241)zaniami, takimi jak SOAP, które do po(cid:228)(cid:241)czenia si(cid:246) z serwerem wymagaj(cid:241) z(cid:228)o(cid:276)onego stosu klienta. Niestety, podobnie jak ka(cid:276)de z(cid:228)o(cid:276)one zagadnienie informatyczne termin REST powoduje niejasno(cid:264)ci i dyskusj(cid:246). Czasami u(cid:276)ywany jest niew(cid:228)a(cid:264)ciwie, a cza- sami zwolennicy us(cid:228)ugi REST zbytnio przesadzaj(cid:241) z budowaniem (cid:264)wia- domo(cid:264)ci tego, (cid:276)e niepoprawne jest stosowanie go w mniej czystej formie. W tym miejscu chcemy si(cid:246) zaj(cid:241)(cid:232) zwi(cid:241)zanymi z tym w(cid:241)tpliwo(cid:264)ciami. Us(cid:293)uga REST w czystej formie W swojej najczystszej formie us(cid:228)uga REST jest zgodna z wytycznymi zawar- tymi w pracy doktorskiej Fieldinga, a tak(cid:276)e w nowszych pracach i wpisach zamieszczonych na blogu. Centralne znaczenie dla stylu us(cid:228)ugi REST ma poj(cid:246)cie kryj(cid:241)ce si(cid:246) pod skrótem HATEOAS (Hypermedia as the Engine of Appli- cation State). Interfejs API, który przestrzega regu(cid:228) HATEOAS, identyfikuje si(cid:246) sam za pomoc(cid:241) kontraktu bardzo ró(cid:276)ni(cid:241)cego si(cid:246) od kontraktów innych typów interfejsów API. Zamiast definiowania listy dzia(cid:228)a(cid:254), jakie klient mo(cid:276)e zre- alizowa(cid:232) w dokumencie statycznym, taki interfejs API wymaga od u(cid:276)ywaj(cid:241)- cego go klienta wykrycia funkcji zapewnianych przez interfejs. Klient, który korzysta z interfejsu opartego na us(cid:228)udze REST, (cid:228)(cid:241)czy si(cid:246) najpierw z ser- werem i wykonuje metod(cid:246) GET dla g(cid:228)ównego identyfikatora URI. Z kolei ten identyfikator zwraca list(cid:246) dodatkowych identyfikatorów URI, które mog(cid:241) by(cid:232) u(cid:276)ywane na potrzeby dodatkowych operacji itp. Inaczej mówi(cid:241)c, klient interfejsu API REST realizuje nast(cid:246)puj(cid:241)ce czynno(cid:264)ci: GET http://api.myapi.com/ Metoda zwraca dokument „powitalny”, który zawiera list(cid:246) dodatko- wych identyfikatorów URI. Kwestie techniczne projektu interfejsów API (cid:95) 93 Kup książkęPoleć książkę GET http://api.myapi.com/customers Klient stwierdza, (cid:276)e jeden z odsy(cid:228)aczy w dokumencie „powitalnym” opisuje sposób uzyskania listy klientów, dlatego wywo(cid:228)uje ten identy- fikator URI (je(cid:264)li odsy(cid:228)acz ten okaza(cid:228) si(cid:246) niepoprawny, klient nie po- winien go u(cid:276)ywa(cid:232) — technologia HATEOAS wyklucza trwa(cid:228)e umiesz- czanie identyfikatorów URI po stronie klienta). POST http://api.myapi.com/customers Klient stwierdza, (cid:276)e metoda GET z poprzedniego kroku zwróci(cid:228)a inny odsy(cid:228)acz do identyfikatora URI, który mo(cid:276)e by(cid:232) stosowany do dodania nowego klienta, dlatego klient wywo(cid:228)uje ten odsy(cid:228)acz. Klient nie zmienia si(cid:246) Rzecz w tym, aby nigdy nie umieszcza(cid:232) identyfikatora URI na trwa(cid:228)e, lecz by wykrywa(cid:232) go za pomoc(cid:241) interfejsu API. Innymi s(cid:228)owy, klient, który przestrzega wszystkich regu(cid:228) us(cid:228)ugi REST, za- chowuje si(cid:246) dok(cid:228)adnie tak jak cz(cid:228)owiek przegl(cid:241)daj(cid:241)cy witryn(cid:246) internetow(cid:241), korzystaj(cid:241)c wy(cid:228)(cid:241)cznie z wy(cid:264)wietlanych odsy(cid:228)aczy (klient ignoruj(cid:241)cy wytyczne HATEOAS zachowuje si(cid:246) z kolei jak u(cid:276)ytkownik, który tworzy zak(cid:228)adki dla konkretnych stron znajduj(cid:241)cych si(cid:246) g(cid:228)(cid:246)boko w strukturze identyfikato- rów URI witryny; w pewnym momencie takie zak(cid:228)adki przestan(cid:241) si(cid:246) sprawdza(cid:232)). Klienty i serwery zgodne z regu(cid:228)ami HATEOAS s(cid:241) rzeczywi(cid:264)cie skalowalne i rozszerzalne. Serwer mo(cid:276)e zmieni(cid:232) posta(cid:232) i funkcjonalno(cid:264)(cid:232) interfejsu API, a nawet usun(cid:241)(cid:232) okre(cid:264)lone funkcje bez negatywnego wp(cid:228)ywu na klienta, poniewa(cid:276) zosta(cid:228) on tak zbudowany, aby dynamicznie dostosowywa(cid:228) si(cid:246) do zmian po stronie serwera. Pragmatyczna us(cid:293)uga REST Je(cid:264)li w przesz(cid:228)o(cid:264)ci korzystano z interfejsów API REST, tre(cid:264)(cid:232) wcze(cid:264)niejszego punktu mo(cid:276)e brzmie(cid:232) obco. Prawdopodobnie u(cid:276)ywano interfejsów API REST, które wcale nie dzia(cid:228)aj(cid:241) w sposób opisany w tym punkcie. By(cid:232) mo(cid:276)e zamiast stosowania jedynie odsy(cid:228)aczy zwróconych przez serwer przyzwy- czajono si(cid:246) do trwa(cid:228)ego wstawiania identyfikatorów URI. Czasami ma to miejsce, poniewa(cid:276) tak zwane interfejsy API REST wcale nie bazuj(cid:241) na us(cid:228)udze REST, lecz po prostu jako metod(cid:246) komunikacji wykorzystuj(cid:241) format JSON lub XML za po(cid:264)rednictwem protoko(cid:228)u HTTP (wkrótce zostanie opisany taki interfejs API). 94 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę Cz(cid:246)(cid:264)ciej jednak jest tak, gdy(cid:276) interfejsy API by(cid:228)y (cid:264)wiadomie tworzone w innym celu. S(cid:241) one zgodne z regu(cid:228)ami REST, lecz nie wszystkimi. Takie in- terfejsy API s(cid:241) (cid:228)atwe do opanowania i obs(cid:228)ugi, a ponadto reprezentuj(cid:241) wi(cid:246)k- szo(cid:264)(cid:232) publicznych interfejsów. W odniesieniu do tych interfejsów API b(cid:246)- dziemy u(cid:276)ywa(cid:232) terminu pragmatycznej us(cid:228)ugi REST. Dlaczego wiele interfejsów API zosta(cid:228)o zaprojektowanych w taki „pragma- tyczny” sposób? Po cz(cid:246)(cid:264)ci wynika to z faktu, (cid:276)e zasady HATEOAS sta- wiaj(cid:241) programi(cid:264)cie po stronie klienta poprzeczk(cid:246) bardzo wysoko. Progra- mista, który nieumy(cid:264)lnie lub celowo trwale umie(cid:264)ci (cid:264)cie(cid:276)k(cid:246) identyfikatora URI w aplikacji, mo(cid:276)e w przysz(cid:228)o(cid:264)ci dozna(cid:232) szoku, a zespó(cid:228) tworz(cid:241)cy in- terfejs API po stronie serwera mo(cid:276)e po prostu poinformowa(cid:232) klienta o braku mo(cid:276)liwo(cid:264)ci zapewnienia zgodno(cid:264)ci ze specyfikacj(cid:241). Takie interfejsy API mog(cid:241) te(cid:276) by(cid:232) projektowane w ten sposób, gdy(cid:276) nowocze- sna technologia zwi(cid:241)zana z interfejsami API (obejmuj(cid:241)ca u(cid:276)ycie serwerów mediacji mi(cid:246)dzy klientem a serwerami, które udost(cid:246)pniaj(cid:241) interfejsy API umo(cid:276)liwiaj(cid:241)ce ich dostawcom dynamiczne ponowne zapisywanie identy- fikatorów URI i tre(cid:264)ci) sprawia, (cid:276)e bardziej funkcjonalne jest utrzymywanie spójnej struktury identyfikatorów URI. Cho(cid:232) teoretycznie HATEOAS to dobra metoda w przypadku projektowania interfejsu API, w praktyce mo(cid:276)e nie mie(cid:232) zastosowania. Wa(cid:276)ne jest uwzgl(cid:246)d- nienie odbiorców interfejsu API i ich mo(cid:276)liwych metod budowania aplikacji bazuj(cid:241)cych na interfejsie, a tak(cid:276)e wzi(cid:246)cie tego pod uwag(cid:246) przy podejmowaniu decyzji projektowych. W niektórych sytuacjach HATEOAS mo(cid:276)e nie by(cid:232) w(cid:228)a(cid:264)ciwym wyborem. Zasady pragmatycznej us(cid:293)ugi REST W wariancie pragmatycznym us(cid:228)ugi REST wykorzystywane s(cid:241) jej najlepsze elementy. W tym przypadku zdano sobie spraw(cid:246) z tego, (cid:276)e programistom zale(cid:276)y na jak najszybszym zaznajomieniu si(cid:246) z mo(cid:276)liwo(cid:264)ciami interfejsu API, a ponadto chc(cid:241) z nich skorzysta(cid:232) bez konieczno(cid:264)ci pisania du(cid:276)ej ilo(cid:264)ci dodatkowego kodu. Proponujemy nast(cid:246)puj(cid:241)ce zasady pragmatycznej us(cid:228)ugi REST: Identyfikatory URI s(cid:241) istotne Dobrze opracowany wzorzec identyfikatorów URI powoduje, (cid:276)e inter- fejs API jest (cid:228)atwy do zastosowania, poznania i rozszerzenia, tak jak ma to miejsce w przypadku starannie zaprojektowanego interfejsu API powi(cid:241)zanego z tradycyjnym j(cid:246)zykiem programowania. W us(cid:228)udze REST w czystej postaci regu(cid:228)a ta jest zast(cid:246)powana przez HATEOAS. Kwestie techniczne projektu interfejsów API (cid:95) 95 Kup książkęPoleć książkę Parametry s(cid:241) istotne U(cid:276)yj standardowego i (cid:228)atwego do zidentyfikowania zestawu opcjonal- nych operacji dla ka(cid:276)dego wywo(cid:228)ania interfejsu API. Format danych jest istotny Spraw, aby programi(cid:264)ci bez trudu mogli zrozumie(cid:232), jakiego rodzaju danych oczekuje interfejs API, jakiego typu dane zostan(cid:241) przez niego zwrócone, a tak(cid:276)e jak to zmieni(cid:232). Kody powrotu s(cid:241) istotne U(cid:276)yj kodu 404, gdy na przyk(cid:228)ad (cid:264)cie(cid:276)ka nie prowadzi do rzeczywistego obiektu lub kolekcji, a nie zwracaj ogólnego kodu b(cid:228)(cid:246)du, który wymaga w(cid:228)a(cid:264)ciwego zinterpretowania przez u(cid:276)ytkownika. Wszystko inne powinno by(cid:232) ukryte Informacje o zabezpieczeniach, ograniczaniu transferu, routingu itp. mog(cid:241) i powinny by(cid:232) ukrywane w nag(cid:228)ówkach protoko(cid:228)u HTTP. Ustal przejrzyste konwencje oznaczania wersji Czy na przyk(cid:228)ad identyfikator URI powinien zawiera(cid:232) numer wersji albo czy powinien on by(cid:232) parametrem? Jaka wersja powinna zosta(cid:232) do- starczona w przypadku niespe(cid:228)nienia dowolnego z tych warunków? Oczywi(cid:264)cie w tym przypadku przyjmuje si(cid:246), (cid:276)e Twój interfejs API w ogóle korzysta z wersji. W szczególno(cid:264)ci powy(cid:276)sze zasady sugeruj(cid:241) nast(cid:246)puj(cid:241)ce regu(cid:228)y dotycz(cid:241)ce identyfikatorów URI: (cid:120) (cid:263)cie(cid:276)ki URI odwo(cid:228)uj(cid:241)ce si(cid:246) do kolekcji obiektów powinny uwzgl(cid:246)d- nia(cid:232) rzeczownik w liczbie mnogiej, na przyk(cid:228)ad /klienci, aby odnosi(cid:232) si(cid:246) do zbioru wszystkich klientów. (cid:120) (cid:263)cie(cid:276)ki URI odwo(cid:228)uj(cid:241)ce si(cid:246) do pojedynczego obiektu powinny zawie- ra(cid:232) rzeczownik w liczbie pojedynczej, po którym nast(cid:246)puje unikalny klucz podstawowy. Na przyk(cid:228)ad /klienci/Bogdan odwo(cid:228)uje si(cid:246) do klienta z podstawowym identyfikatorem Bogdan, a /konta/123456 odnosi si(cid:246) do konta o numerze 123456. (cid:120) Poprawne jest rozpocz(cid:246)cie identyfikatora URI od (cid:264)cie(cid:276)ki identyfikuj(cid:241)- cej, takiej jak (cid:264)cie(cid:276)ka zawieraj(cid:241)ca numer wersji lub informacje o (cid:264)ro- dowisku. (cid:120) Po (cid:264)cie(cid:276)ce identyfikuj(cid:241)cej w identyfikatorze URI nie powinno si(cid:246) znale(cid:274)(cid:232) nic innego, z wyj(cid:241)tkiem kolekcji i obiektów. 96 (cid:95) Rozdzia(cid:293) 5. Kluczowe zasady projektowania interfejsów API Kup książkęPoleć książkę (cid:120) Zestaw standardowych parametrów zapytania powinien by(cid:232) u(cid:276)ywany dla kolekcji w celu umo(cid:276)liwienia elementowi wywo(cid:228)uj(cid:241)cemu kontro- lowania tego, jaka cz(cid:246)(cid:264)(cid:232) kolekcji zostanie udost(cid:246)pniona. Na przyk(cid:228)ad parametr count pozwala okre(cid:264)li(cid:232) liczb(cid:246) obiektów, które zostan(cid:241) zwró- cone z du(cid:276)ej kolekcji, parametr start s(cid:228)u(cid:276)y do ustalenia pocz(cid:241)tkowego miejsca liczenia obiektów, a parametr q reprezentuje ogólne wyszuki- wanie w dowolnej formie obejmuj(cid:241)ce kolekcj(cid:246) obiektów. Sugerujemy równie(cid:276) nast(cid:246)puj(cid:241)ce regu(cid:228)y dotycz(cid:241)ce obiektów: (cid:120) Pojedyncze obiekty powinny obs(cid:228)ugiwa(cid:232) metod(cid:246) GET dla odczytu, metod(cid:246) PUT dla aktualizacji i metod(cid:246) DELETE dla usuwania. (cid:120) Obiekty kolekcji powinny obs(cid:228)ugiwa(cid:232) metod(cid:246) GET w celu ponownego wczytania ca(cid:228)o(cid:264)ci lub cz(cid:246)(cid:264)ci kolekcji, a tak(cid:276)e metod(cid:246) POST, aby doda(cid:232) nowy obiekt do kolekcji. (cid:120) Pojedyncze obiekty mog(cid:241) obs(cid:228)ugiwa(cid:232) metod(cid:246) POST w celu zapewnienia mo(cid:276)liwo(cid:264)ci zmiany stanu. Za pomoc(cid:241) tej metody mo(cid:276)esz na przyk(cid:228)ad wys(cid:228)a(cid:232) nowy dokument JSON b(cid:241)d(cid:274) XML do obiektu w celu zmiany okre(cid:264)lonych pól albo wywo(cid:228)a(cid:232) zmian(cid:246) stanu lub dzia(cid:228)anie bez zast(cid:246)- powania ca(cid:228)ego obiektu. Przyk(cid:293)ad: projektowanie z wykorzystaniem pragmatycznej us(cid:293)ugi REST W tabeli 5.1 pokazano interfejs API koszyka zakupów, który nie prze- strzega konwencji us(cid:228)ugi REST w czystej postaci. Interfejs nie jest zgodny ani z czystym, ani z pragmatycznym wariantem us(cid:228)ugi REST. Tabela 5.1. Niew(cid:228)a(cid:264)ciwa droga do us(cid:228)ugi REST Zadanie Umieszczanie nowego produktu w koszyku Usuwanie produktu z koszyka Wy(cid:316)wietlanie zawarto(cid:316)ci koszyka Pobieranie produktu w koszyku Usuwanie ca(cid:293)ego koszyka Operacja POST POST GET GET POST Identyfikator URI http://api.zakupy.com/WstawianieNowegoProduktu http://api.zakupy.com/UsuwanieProduktu http://api.zakupy.com/ZawartoscKoszyka?Identyfikator (cid:180)koszyka=X http://api.zakupy.com/WyswietlanieProduktu?Identyfikator (cid:180)koszyka=X identyfikatorproduktu=Y http://api.zakupy.com/UsuwanieKoszyka Kwestie techniczne projektu interfejsów API (cid:95) 97 Kup książkęPoleć książkę Ten interfejs API nie jest trudny w u(cid:276)yciu, ale konieczne jest opanowanie poszczególnych operacji. Mo(cid:276)e to by(cid:232) k(cid:228)opotliwe, je(cid:264)li istnieje wiele opera- cji lub interfejs API si(cid:246) rozwija. Wyobra(cid:274) sobie, co by by(cid:228)o, gdyby oprócz koszyka pojawi(cid:228)o si(cid:246) 50 innych typów obiektów, a wraz z nimi ca(cid:228)y zestaw operacji. Z tego powodu opracowana dokumentacja interfejsu API by(cid:228)aby obszerna, a ponadto wymaga(cid:228)aby przeszukiwania dla ka(cid:276)dego nowego wywo(cid:228)ania dotycz(cid:241)cego interfejsu. Projektant mo(cid:276)e by(cid:232) na przyk(cid:228)ad zmu- szony do sprawdzenia, czy operacja InsertNewItem umieszcza jedynie pro- dukt w koszyku, natomiast operacja InsertNewItemIntoWishlist musi zosta(cid:232) u(cid:276)yta dla listy (cid:276)ycze(cid:254) klienta i tak dalej a(cid:276) do znudzenia. (cid:227)atwiejszy do opanowania jest koszyk zakupów bazuj(cid:241)cy na wariancie pragmatycznym us(cid:228)ugi REST, który zaprezentowano w tabeli 5.2. Tabela 5.2. Koszyk zakupów bazuj(cid:241)cy na wariancie pragmatycznym us(cid:228)ugi REST Zadanie Umieszczanie nowego produktu w koszyku Usuwanie produktu z koszyka Wy(cid:316)wietlanie zawarto(cid:316)ci koszyka Pobieranie produktu w koszyku Zast(cid:253)powanie produktu w ca(cid:293)o(cid:316)ci Usuwanie ca(cid:293)ego koszyka Operacja POST DELETE GET GET PUT DELETE Identyfikator URI http://api.zakupy.com/koszyk/Nazwakoszyka http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/ Nazwaproduktu http://api.zakupy.com/koszyk/Nazwakoszyka http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/ Nazwaproduktu http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/ Nazwaproduktu http://
Pobierz darmowy fragment (pdf)

Gdzie kupić całą publikację:

Interfejs API. Strategia programisty
Autor:
, ,

Opinie na temat publikacji:


Inne popularne pozycje z tej kategorii:


Czytaj również:


Prowadzisz stronę lub blog? Wstaw link do fragmentu tej książki i współpracuj z Cyfroteką: