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.
3
Spis treļci
Przedmowa ......................................................................................9
1. Możliwoļci interfejsów API .......................................................... 13
Dlaczego napisano tö ksiñĔkö?
15
Dla kogo przeznaczona jest ta ksiñĔka?
17
Czym jest interfejs API?
17
Czym interfejs API róĔni siö od witryny internetowej?
18
Interfejsy API i witryny internetowe
majñ jednakĔe wiele wspólnego
20
Kto korzysta z interfejsu API?
21
Typy interfejsów API
21
Dlaczego teraz?
23
2. Interfejsy API jako strategia biznesowa .......................................25
Rozwój interfejsów API
28
Dlaczego interfejs API moĔe okazaè siö potrzebny?
30
Potrzebujesz drugiej aplikacji dla urzñdzeþ przenoĈnych
30
Klienci lub partnerzy pytajñ o interfejs API
31
Witryna internetowa zaczyna byè uĔywana
do wyodröbniania wyĈwietlanych danych
32
Wymagasz wiökszej elastycznoĈci
w zakresie udostöpniania treĈci
32
Istniejñ dane, które majñ zostaè udostöpnione
33
Konkurencja z branĔy korzysta z interfejsu API
33
Chcesz umoĔliwiè potencjalnym partnerom poznanie nowoĈci
34
Wymagasz skalowania integracji z klientami i partnerami
34
Interfejs API ulepsza architekturö technicznñ
36
3. Ĥaħcuch wartoļci interfejsu API ................................................... 37
Definiowanie äaþcucha wartoĈci: zadawanie kluczowych pytaþ
38
Tworzenie äaþcucha wartoĈci prywatnego interfejsu API
41
Metody uĔycia prywatnego interfejsu API
42
Zalety prywatnych interfejsów API
45
ZagroĔenia zwiñzane z prywatnymi interfejsami API
46
4
_
Spis treļci
Tworzenie äaþcucha wartoĈci publicznych interfejsów API
47
Metody wykorzystania publicznego interfejsu API
48
Zalety publicznych interfejsów API
51
ZagroĔenia zwiñzane z publicznymi interfejsami API
52
Przemiana: publiczny interfejs API zamiast prywatnego,
prywatny interfejs zamiast publicznego
53
Netflix: zamiana publicznego interfejsu API na prywatny
54
Modele biznesowe z interfejsami API
uĔywane do wspóäpracy z partnerami
56
Zwiökszanie zasiögu: wiöcej aplikacji, wiöcej platform
56
Osiñganie poĈredniego dochodu
57
Zwiökszanie innowacji we wspóäpracy z partnerami
58
Zwiökszanie wartoĈci aplikacji poprzez integracjö
58
Wariant uĔycia po czöĈci darmowy, a po czöĈci päatny
59
Postrzeganie modeli biznesowych interfejsów API przez firmö
ProgrammableWeb.com
60
4. Przygotowywanie strategii produktów z interfejsami API .........65
OkreĈlanie jasnego celu biznesowego
66
OkreĈlenie wizji dotyczñcej interfejsu API
66
Podstawy strategii dotyczñcej interfejsu API
68
Interfejsy API wymagajñ sponsora biznesowego
69
Typy strategii zwiñzanych z interfejsami API
70
Strategie dotyczñce prywatnych interfejsów API
71
Strategie dotyczñce publicznych interfejsów API
72
Tworzenie zespoäu
73
Promotor projektantów
74
ZastrzeĔenia dotyczñce interfejsów API
76
5. Kluczowe zasady projektowania interfejsów API .......................81
Projektowanie interfejsów API dla konkretnych grup odbiorców
82
Projektowanie pod kñtem projektantów
83
Projektowanie pod kñtem uĔytkowników aplikacji
85
Najlepsze praktyki zwiñzane z projektem interfejsów API
85
OdróĔnij wäasny interfejs API
86
Zapewnij äatwoĈè testowania i uĔywania interfejsu API
87
Zapewnij äatwoĈè zrozumienia interfejsu API
88
Nie rób niczego dziwnego
89
Mniej znaczy wiöcej
90
Ukierunkowanie na konkretny segment projektantów
91
Spis treļci
_
5
Kwestie techniczne projektu interfejsów API
91
Usäuga REST
92
Przykäad: projektowanie z wykorzystaniem
pragmatycznej usäugi REST
97
Kontrola wersji i projekt interfejsu API
100
Projektowanie infrastruktury dla interfejsów API
106
Centrum danych czy chmura?
106
Strategie buforowania
107
Kontrolowanie ruchu sieciowego generowanego
przez interfejsy API
109
6. Zabezpieczenia interfejsów API
i zarzédzanie użytkownikami ...................................................... 111
Zarzñdzanie uĔytkownikami
112
Czy niezbödne jest rozpoczynanie od podstaw?
113
Pytania, które naleĔy zadaè odnoĈnie do zarzñdzania
uĔytkownikami
113
Identyfikacja
114
Uwierzytelnianie: potwierdzanie toĔsamoĈci uĔytkownika
116
Nazwy uĔytkowników i hasäa
116
Uwierzytelnianie oparte na sesji
117
Inne metody uwierzytelniania
118
Protokóä OAuth
118
Ulepszanie uwierzytelniania za pomocñ protokoäu SSL
120
Szyfrowanie
122
Wykrywanie zagroĔeþ i zapobieganie im
123
„Wstrzykiwanie” kodu SQL
124
Ataki z wykorzystaniem formatów XML i JSON
124
Maskowanie danych
125
Ogólne zalecenia
126
Zalecenia dotyczñce ochrony danych interfejsu API
126
Zalecenia dotyczñce zabezpieczeþ interfejsów API
126
7. Kwestie prawne zwiézane ze strategié interfejsu API .............. 129
Zarzñdzanie prawami
130
Praktyka: zarzñdzanie prawami w organizacji NPR
130
Umowy i warunki uĔytkowania
133
Zasady prywatnoĈci
135
Zasady utrzymywania danych
136
Przypisywanie wäaĈciciela treĈci i budowanie ĈwiadomoĈci marki
137
Reagowanie na niewäaĈciwe uĔycie
137
6
_
Spis treļci
8. Obsĥuga interfejsu API i zarzédzanie nim ................................... 139
Obsäuga interfejsu API
140
Informacje operacyjne na Ĕñdanie:
strona statusu interfejsu API
141
Radzenie sobie z problemami operacyjnymi
142
Umowy SLA
143
Zarzñdzanie problemami
143
Monitorowanie i wsparcie operacyjne
144
Dokumentowanie interfejsu API
145
Zestaw procedur operacyjnych
147
Metody zarzñdzania ruchem sieciowym
148
Zarzñdzanie ruchem sieciowym na poziomie biznesowym
148
Operacyjne zarzñdzanie ruchem sieciowym
152
Zarzñdzanie ruchem sieciowym i skalowalnoĈè
154
Bramy interfejsów API
155
9. Okreļlanie miary sukcesu interfejsu API .................................... 159
Obsäuga metryk interfejsów API
160
Dlaczego gromadzone sñ wzorce wykorzystania
na potrzeby metryk?
161
ēñdania i odpowiedzi
162
WyĈwietlenia
162
LojalnoĈè
163
Metryki operacyjne
164
Metryki zwiñzane z efektywnoĈciñ
166
Metryki zwiñzane z wydajnoĈciñ
166
Kluczowe pytania zwiñzane z wydajnoĈciñ interfejsów API
167
10. Angażowanie projektantów w proces adaptacji ....................... 173
Co motywuje projektantów?
174
Kluczowe elementy programu dla projektantów
174
Produkt (czyli najpierw musisz dysponowaè znakomitym
interfejsem API!)
175
Dostöp do interfejsu API i jego twórcy
175
Warunki biznesowe i oczekiwania wzglödem umów SLA
176
TreĈè
177
ćwiadomoĈè istnienia interfejsu API
177
Skoncentruj siö na peänym komforcie pracy projektantów
178
SpoäecznoĈè
179
Spis treļci
_
7
Anatomia portalu projektantów
179
Dziaäania zalecane i niezalecane
w procesie angaĔowania projektantów
184
Dziaäania zalecane
184
Dziaäania niezalecane
188
11. Epilog: to dopiero poczétek ..........................................................191
Skorowidz .................................................................................... 193
81
ROZDZIAĤ 5.
Kluczowe zasady projektowania
interfejsów API
W poczñtkowych etapach rozwoju projekt interfejsów API stanowi sztukö.
Niemniej jednak zdobyto wystarczajñce doĈwiadczenie do tego, aby opra-
cowaè wartoĈciowñ listö bäödów do unikania, a takĔe zasady zapewniajñce
powodzenie. ēeby wäaĈciwie zaprojektowaè interfejs API, konieczne bö-
dzie uwzglödnienie wiökszoĈci zagadnieþ poruszonych w tej ksiñĔce. Na
projekt majñ wpäyw przyjöta strategia oraz grupa odbiorców, jak równieĔ
zasoby biznesowe planowane do udostöpnienia. OczywiĈcie dla projektu
znaczenie ma teĔ wybrana metoda technologiczna. W tym rozdziale skon-
centrowano siö na nastöpujñcych trzech obszarach:
x
projektowanie interfejsu API dla róĔnych grup odbiorców;
x
zapewnienie przeglñdu kwestii technologicznych;
x
wyróĔnienie ogólnych zagadnieþ projektowych.
Strategia dotyczñca interfejsów API skupia siö gäównie na utworzeniu co
najmniej jednego kanaäu z interfejsem API w celu uäatwienia osiñgniöcia
przyjötych celów biznesowych. Gdy ludzie korzystajñ z interfejsu API, tak
naprawdö nie zastanawiajñ siö nad wartoĈciñ jego samego. Zainteresowani
sñ wartoĈciñ, jakñ uzyskajñ za poĈrednictwem interfejsu, czyli zasobami
biznesowymi (produktami i usäugami) udostöpnianymi za jego pomocñ.
Przy projektowaniu interfejsów API próbujemy udostöpniè zasoby bizne-
sowe projektantom, tak aby mogli tworzyè aplikacje zapewniajñce wartoĈci
uĔytkownikom koþcowym, którzy nastöpnie bödñ mieli moĔliwoĈè uzy-
skania okreĈlonego rodzaju wartoĈci pozwalajñcej zakoþczyè cykl korzyĈci
zwiñzanych z interfejsem API.
82
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Ogólnie rzecz biorñc, najlepsze interfejsy API sñ starannie zaprojektowane,
äatwe do opanowania, z logicznñ strukturñ i wewnötrznie spójne. Dziöki
temu projektanci mogñ stwierdziè, jak ze wzglödnym powodzeniem wyeli-
minowaè wszelkie niejasnoĈci. Interfejs API powinien byè trochö jak samo-
chód. KaĔde auto wyposaĔone jest w kierownicö oraz pedaäy hamulca i gazu.
MoĔesz uznaè, Ĕe Ĉwiatäa awaryjne, otwieranie bagaĔnika lub radio sñ tro-
chö inne w róĔnych modelach samochodów, ale do rzadkoĈci naleĔy sytu-
acja, w której doĈwiadczony kierowca nie wie, jak prowadziè wypoĔ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ö, Ĕe w odniesie-
niu do interfejsów API naleĔy rozwaĔyè dwie podstawowe grupy.
Projektanci (lub nawet szerzej rzecz ujmujñc, zespoäy techniczne i tworzñ-
ce produkty) to bezpoĈrednia grupa odbiorców, która korzysta z interfejsu
API i buduje na jego bazie aplikacje.
UĔytkownicy koþcowi to poĈrednia grupa odbiorców, która stosuje aplikacje
utworzone za pomocñ interfejsu API.
Aby okreĈliè grupö odbiorców, naleĔy siö najpierw zastanowiè nad sfor-
muäowaniem wizji dotyczñcej interfejsu API. Pozwoli to stwierdziè, co jest
celem interfejsu. W dalszej kolejnoĈci moĔna ustaliè, którzy odbiorcy spo-
Ĉród tych ich typów skorzystajñ z interfejsu API oraz jak musi wyglñdaè
model interakcji. Czy interfejs jest projektowany dla dziaäów, które bazujñ
na informacjach z systemu ERP? Czy moĔe interfejs ma byè przeznaczony dla
projektantów aplikacji dla urzñdzeþ przenoĈnych, najwaĔniejszych 10 part-
nerów firmy, czy sprzedawców stowarzyszonych z firmñ?
PrzeprowadĒ analizö segmentacji uĔytkowników koþcowych i (lub) pro-
jektantów oraz ustal priorytety dla segmentów. JeĈli poczñtkowa odpowiedĒ
wskazuje na wszystkich jako odbiorców, sugerujemy trochö staranniejsze
przemyĈlenie tej kwestii, przynajmniej w przypadku okreĈlania priorytetów.
Wyzwaniem jest projektowanie zarówno z myĈlñ o projektantach tworzñ-
cych interfejs API, jak i uĔytkownikach koþcowych, którzy bödñ stosowaè
interfejs API. Zajmiemy siö teraz przybliĔeniem obu zagadnieþ.
Projektowanie interfejsów API dla konkretnych grup odbiorców
_
83
Projektowanie pod kétem projektantów
Projektantów moĔna podzieliè na wiele typów i podkategorii. Interfejs API
moĔe byè tworzony z myĈlñ o nielicznej, bardzo specyficznej grupie pro-
jektantów o wysokich kompetencjach uĔywajñcych konkretnej technologii
lub dla kaĔdego na Ĉwiecie, komu firma chciaäaby zapewniè dostöp do
swoich zasobów biznesowych. W zwiñzku z tym warto zaznajomiè siö
z segmentacjñ kategorii projektantów. Dziöki temu wybór platformy tech-
nicznej stanie siö bardziej oczywisty.
Inaczej mówiñc, zespoäy budujñce interfejsy API bödñ zwykle zmuszone
do dokonywania wielu wyborów dotyczñcych technologii. Protokóä SOAP
czy REST? Format XML czy JSON? Protokóä OAuth czy coĈ innego? Od-
powiedzi na te pytania bödñ bardziej niĔ cokolwiek innego zaleĔne od odbior-
ców, którzy skorzystajñ z interfejsu API. Prezentujemy jednak kilka reko-
mendacji.
Nasze rekomendacje technologiczne dla interfejsów API
JeĈli nie ma Ĕadnych konkretnych powodów, aby postñpiè inaczej, oto
pierwsze moĔliwoĈci, jakie powinny zostaè obecnie wybrane przez do-
wolny zespóä tworzñcy interfejs API:
x
„Pragmatyczna” usäuga REST na potrzeby struktury, poniewaĔ uäatwia
opanowanie, wykorzystanie i rozszerzenie interfejsu API w wiökszym
stopniu niĔ inne technologie, takie jak SOAP (w dalszej czöĈci ksiñĔki
zostanie omówiona usäuga REST i jej „pragmatyczny” wariant).
x
JSON jako format danych pobieranych i zwracanych przez interfejs
API, gdyĔ upraszcza programistom generowanie danych i korzystanie
z nich.
x
Protokóä OAuth do zabezpieczania, poniewaĔ zapobiega propagacji
haseä w internecie, a jednoczeĈnie obsäuguje róĔne metody uwierzy-
telniania uĔytkownika koþcowego.
JeĈli te technologie nie sñ Ci jeszcze znane, nie przejmuj siö. W dalszej czöĈci
rozdziaäu zajmiemy siö usäugñ REST i formatem JSON, a protokóä OAuth
wraz z innymi zagadnieniami zwiñzanymi z zabezpieczeniami zostanie
omówiony w rozdziale 6.
Co wiöcej, opisujemy te technologie jako pierwszñ opcjö wyboru, a nie ja-
ko jedynñ. Nowoczesne serwery aplikacji i platformy z interfejsem API
umoĔliwiajñ obsäugiwanie wiöcej niĔ jednej takiej technologii. Na przykäad
84
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
zapewniajñ one interfejs API, który wspiera technologie XML i JSON, albo
udostöpniajñ interfejsy API protokoäu SOAP i usäugi REST.
Najlepsze procedury techniczne
zwiézane z interfejsem API firmy Tumblr
Czy chciaäbyĈ siö podzieliè jakimikolwiek najlepszymi procedurami technicznymi
zwiñzanymi z interfejsem API firmy Tumblr?
ZaleĔy nam na tym, aby interfejs API byä äatwy do opanowania bez uĔy-
cia dokumentacji. Dziöki temu, jak zostaäy zaprojektowane stosowane
przez nas identyfikatory URI, powinno byè po prostu moĔliwe przejĈcie
do poziomu wiersza poleceþ.
Staramy siö tylko w nieznacznym stopniu modyfikowaè interfejs API. Jednñ
z wielkich ironii losu zwiñzanych z witrynñ internetowñ jest to, Ĕe mogö
wprowadziè w niej zmiany w dowolnym Ĕñdanym momencie, a z kolei
interfejs API jest wyjñtkowo delikatny w tym sensie, Ĕe moĔe spowodo-
waè, iĔ przestanñ dziaäaè aplikacje projektantów korzystajñcych z tego
interfejsu. Kontrola wersji to trwajñcy proces.
Derek Gottfrid, dyrektor ds. produktów w firmie Tumblr
Choè warto zaczñè od technologii REST, JSON i OAuth przy rozwaĔaniu zasto-
sowania interfejsu API, sñ powody, aby nie decydowaè siö na te rozwiñzania.
Usäuga REST moĔe powodowaè mniej elastyczne interakcje miödzy klien-
tami a interfejsem API. Mogñ byè dostöpne lepsze metody osiñgniöcia po-
dobnego wyniku, bo dajñce wiökszñ efektywnoĈè.
Prostszy model obiektowy formatu JSON jest preferowany w wielu sytu-
acjach w celu zmniejszenia liczby bajtów, co poprawia wydajnoĈè dostar-
czania bajtów za pomocñ protokoäu HTTP. Jözyk XML stwarza potencjaä
uĔycia bardziej rozbudowanych znaczników i opcji semantycznych. Ponadto
w przypadku formatu XML istnieje znacznie wiöcej standardów organizowa-
nia treĈci niĔ dla formatu JSON. Oznacza to, Ĕe aplikacje analizujñce oraz
inne biblioteki kodu mogñ zwiökszyè efektywnoĈè projektowania aplikacji.
Choè protokóä OAuth znakomicie nadaje siö do zabezpieczania transakcji
interfejsu API, najlepiej dostosowany jest do potrzeb duĔych grup nieznanych
projektantów, którzy próbujñ uĔyè interfejsu API firmy. JeĈli odbiorcy doce-
lowi to niewielka grupa projektantów firmy, protokóä OAuth moĔe okazaè siö
przesadñ.
Najlepsze praktyki zwiézane z projektem interfejsów API
_
85
Kluczem do podjöcia takich decyzji jest zrozumienie tego, kto bödzie ko-
rzystaè z interfejsu API, a takĔe tego, w jaki sposób takie osoby bödñ tworzyè
aplikacje interesujñce dla uĔytkowników koþcowych.
Projektowanie pod kétem użytkowników aplikacji
Im lepiej moĔesz zrozumieè, jaki typ dostöpu jest wymagany przez uĔytkow-
ników koþcowych, tym wiöcej informacji uzyskasz na temat tego, co ma zo-
staè uwzglödnione w interfejsie API, oraz tego, jak w najwiökszym stopniu
uäatwiè dostöp. Firmy publikujñce interfejsy API powinny siö zastanowiè,
czego uĔytkownicy oczekujñ od ich zasobów biznesowych i jak mogñ zapew-
niè dostöp, który spowoduje zwiökszenie wykorzystania interfejsu API.
Trudno w tym przypadku o generalizowanie, poniewaĔ czösto nie jest oczy-
wiste, jakiego rodzaju aplikacje bödñ tworzone. Poza tym moĔesz tylko w za-
rysie wyobraĔaè sobie skrywane potrzeby uĔytkowników koþcowych do-
tyczñce zasobów biznesowych. Co wiöcej, jeĈli po udostöpnieniu interfejsy
API odniosñ sukces, zwykle bödñ stanowiè inspiracjö dla nowych pomysäów
i zastosowaþ, które byè moĔe nie byäy rozwaĔane w fazie projektowania.
Dotyczy to zarówno prywatnych, jak i publicznych interfejsów API.
Na przykä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äoĔeniem (interfejs API serwisu Google Maps),
mogñ byè wykorzystywane z duĔñ äatwoĈciñ, poniewaĔ wiele aplikacji
oferuje realizowanie tych prostych dziaäaþ. Inne, bardziej zäoĔone funkcje
zostaäy dodane póĒniej bñdĒ okazaäy siö przydatne w wyniku ciñgäego
powiökszania siö bazy uĔytkowników. Koþcowy wniosek jest taki, Ĕe im wiö-
cej uzyskasz informacji o populacji uĔytkowników koþcowych i rodzaju
wymaganych przez nich aplikacji, tym lepiej bödziesz poinformowany na
etapie decydowania o tym, jakie funkcje majñ zostaè zaoferowane jako
pierwsze.
Najlepsze praktyki
zwiézane z projektem interfejsów API
Z doĈwiadczenia wiemy, Ĕe w przypadku interfejsów API czöĈè rzeczy siö
udaje, a czöĈè nie. W tym podrozdziale przedstawiamy kilka propozycji,
które uwaĔamy za solidne i najlepsze praktyki zwiñzane z projektem in-
terfejsów API.
86
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Organizacja NPR zna swoich odbiorców
Organizacja NPR opracowaäa swój program zwiñzany z interfejsem API,
bazujñc na dobrej znajomoĈci odbiorców docelowych. Zasadniczo z da-
lekowzrocznoĈci organizacji korzystajñ nastöpujñce cztery grupy:
x
Pracownicy
organizacji NPR to najwiöksza grupa uĔywajñca interfejsu
API, która obsäuguje caäñ infrastrukturö serwisu NPR.org, gäównñ
witrynö internetowñ, a takĔe inne zasoby cyfrowe. Poczñtkowo inter-
fejs byä stosowany do usprawniania systemu zarzñdzania treĈciñ CMS
wspierajñcego witrynö internetowñ. Miaäo to na celu umoĔliwienie uĔycia
niestandardowych kanaäów informacyjnych opracowywanych przez
dziaä redakcyjny i projektowy. Najwiökszñ korzyĈciñ wynikajñcñ z zasto-
sowania interfejsu API byäo utworzenie wielu aplikacji firmowanych
przez organizacjö NPR dla urzñdzeþ przenoĈnych i innych platform.
W efekcie po upäywie niecaäego roku osiñgniöto 100-procentowy wzrost
liczby wyĈwietleþ stron dla wszystkich zasobów cyfrowych.
x
Stacje czäonkowskie organizacji NPR
stanowiñ istotne grono odbiorców.
UĔywajñ one interfejsu API do pobierania treĈci i tworzenia dla swoich
spoäecznoĈci stron zespolonych z treĈciñ o zasiögu lokalnym i ogólno-
krajowym.
x
Interfejs API organizacji NPR stworzyä nowe moĔliwoĈci dla partnerów,
poniewaĔ wiñzaäy siö z nim niskie koszty integracji. Oznaczaäo to, Ĕe
juĔ istniejñce rozwiñzania równieĔ byäy äatwiejsze do utrzymania i roz-
wijania, gdyĔ kanaä komunikacji byä bardziej niezawodny niĔ wczeĈniej,
kiedy rozwiñzania czösto byäy obsäugiwane za pomocñ niestandardo-
wych kanaäów informacyjnych XML, kanaäów RSS lub innych mniej
niĔ optymalnych metod.
x
Czwarta grupa korzystajñca z interfejsu API organizacji NPR to ogóä spoäe-
czeþstwa
. Rozszerzenie interfejsu uäatwiäo wsparcie misji organizacji NPR,
która oferuje usäugö publicznñ, a ponadto zapewniäo zestaw widgetów
i narzödzi wspomagajñcych tworzenie zewnötrznych witryn interne-
towych wykorzystujñcych treĈè tej organizacji w innowacyjny sposób.
Odróżnij wĥasny interfejs API
Podstawowa sprawa: dlaczego projektant powinien uĔyè Twojego interfej-
su API? Czym siö on róĔni od innych rozwiñzaþ? Dlaczego naleĔaäoby
z niego skorzystaè?
Najlepsze praktyki zwiézane z projektem interfejsów API
_
87
Oto kilka moĔliwych sposobów odróĔnienia wäasnego interfejsu API:
x
Dane sñ unikalne, bardziej kompletne lub dokäadniejsze niĔ w przy-
padku interfejsu konkurencji.
x
Oferowane jest lepsze wsparcie bñdĒ äatwiejszy proces rejestrowania.
x
Interfejs API jest solidniejszy, bardziej niezawodny, ciekawszy albo
szybszy niĔ rozwiñzanie alternatywne.
x
Zaproponowane warunki sñ atrakcyjniejsze dla projektantów. Byè mo-
Ĕe oferujesz wiökszy darmowy ruch sieciowy zwiñzany z danymi lub
lepsze stawki.
Zaakcentuj to, dlaczego ktoĈ powinien uĔywaè Twojego interfejsu API, a nie
innego rozwiñzania. MoĔe nim byè publiczny interfejs API konkurencji,
alternatywne Ēródäo danych lub starsza (i bardziej znajoma) metoda po-
wiñzana z prywatnym interfejsem API. MoĔliwe jest teĔ rozróĔnienie ofert
i elementów motywacyjnych zwiñzanych z Twoim interfejsem API. Jedna
ze strategii polega na zaoferowaniu róĔnych wariantów cenowych zaleĔnych
od skali bñdĒ typu wykorzystania. Taka strategia umoĔliwia pozyskanie
wiökszej liczby poziomów subskrybentów interfejsu. CzöĈè wywoäaþ in-
terfejsu API moĔe byè bezpäatna, a czöĈè moĔe wymagaè dokonania päat-
noĈci. MoĔesz zezwoliè na darmowe uĔycie interfejsu w przypadku pu-
blicznej aplikacji, natomiast pobieraè opäatö, gdy wykorzystywany jest on
wewnñtrz firmy.
Zapewnij ĥatwoļë testowania i używania interfejsu API
JeĈli Twój interfejs API jest jednñ z wielu opcji, jego potencjalni uĔytkownicy
mogñ poĈwiöciè na jego wypróbowanie tylko kilka minut. JeĔeli nie mogñ
stwierdziè prawie natychmiastowych postöpów, zainteresujñ siö czymĈ in-
nym. W przypadku udanych programów zwiñzanych z interfejsami API
eliminowane sñ wszystkie bariery odnoszñce siö do uĔytkowania. Istnieje
kilka metod, które to umoĔliwiajñ.
W odniesieniu do prywatnych interfejsów API waĔne jest zademonstrowanie
prawdziwej wartoĈci wynikajñcej z uruchomienia systemu lub aplikacji na
bazie interfejsu API. Na przykäad interfejs moĔe oferowaè znacznie bar-
dziej elastyczny dostöp do treĈci, lepszñ ogólnñ wydajnoĈè, efektywniejsze
cykle projektowania albo innñ korzyĈè. Aby przyspieszyè proces adaptacji
interfejsu API, zidentyfikuj konkretny przypadek uĔycia znaczñcej aplikacji
i zadbaj o uwzglödnienie go w Ĉrodowisku produkcyjnym. Gdy to nastñpi,
moĔliwe bödzie dostrojenie tego przypadku zastosowania i zaprezentowania
88
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
jego wartoĈci. Po wdroĔeniu moĔliwego do zademonstrowania przypadku
uĔycia äatwiejsze bödzie wskazanie go jako przykäadu, który moĔe zostaè
wykorzystany przez innych. Ponadto projektanci, którzy zaimplementowali
ten pierwszy przypadek uĔycia, uäatwiñ proces promowania, pod warun-
kiem Ĕe ich doĈwiadczenie z nim zwiñzane jest pozytywne. Nie zapomnij
postaraè siö o poparcie odpowiednich osób z zarzñdu i (lub) zespoäów za-
rzñdzajñcych, aby usprawniè sobie dalsze dziaäania.
W przypadku publicznych interfejsów API jednñ z metod postöpowania jest
oferowanie okreĈlonego poziomu darmowego dostöpu. Wielu projektantów
nawet nie rozwaĔy uĔycia interfejsu, jeĈli bödzie on zapewniaè tylko päat-
ne opcje. Na tym etapie cyklu pozyskiwania klientów projektant moĔe nie
wiedzieè, czy Twój interfejs speänia jego wymagania lub czy model bizne-
sowy jego aplikacji bödzie uwzglödniaè päatny dostöp.
Programy, które odniosäy sukces, sprawiajñ teĔ, Ĕe testowanie interfejsu
API jest wyjñtkowo proste i szybkie. Gdy to tylko moĔliwe, zapewniajñ one
natychmiastowñ satysfakcjö. Projektantom wyĈwietlajñcym interfejs API
serwisu Twitter prezentowana jest konsola, która pozwala na bäyskawiczne
testowanie. Firma Twitter idzie o krok dalej, oferujñc operacje interfejsu,
które nie wymagajñ Ĕadnego rejestrowania ani uwierzytelniania (jest to na
przykäad operacja powiñzana z publicznñ osiñ czasu, umoĔliwiajñca pro-
jektantom uzyskanie dostöpu do ostatnich aktualizacji statusu dla wszyst-
kich publicznych uĔytkowników na caäym Ĉwiecie).
JeĈli warunkiem zastosowania interfejsu API jest rejestracja, udoskonal proces.
Nie jest dobrym pomysäem zadawanie wiöcej niĔ kilku pytaþ kwalifikujñ-
cych lub implementowanie procesu zatwierdzania, w ramach którego musisz
skontaktowaè siö z projektantem. Zanim to nastñpi, projektant moĔe juĔ
straciè zainteresowanie interfejsem API.
Inaczej sytuacja wyglñda w przypadku prywatnych interfejsów API, dla któ-
rych niezbödna jest oficjalna umowa partnerska. Im wiöcej informacji mo-
Ĕesz zapewniè w celu zachöcenia partnerów do zarejestrowania, tym lepiej.
Zapewnij ĥatwoļë zrozumienia interfejsu API
Najbardziej udane interfejsy API sñ projektowane intuicyjnie. Prostota jest
kluczem, pewnikiem dotyczñcym nie tylko tego, na co interfejs pozwala,
ale teĔ sposobów prezentowania funkcji projektantom. Znakomitym przy-
käadem jest interfejs API usäugi Facebook Graph. Opis tego interfejsu czyta siö
jak ksiñĔkö. Aby zrozumieè, jakie sñ jego moĔliwoĈci, niezbödna jest bardzo
ograniczona dokumentacja.
Najlepsze praktyki zwiézane z projektem interfejsów API
_
89
Stare powiedzenie dotyczñce projektów, które odnosi siö teĔ do interfej-
sów API, brzmi: „Spraw, aby interfejs byä tak prosty, jak to moĔliwe, lecz
nie zbyt prosty”. Twórcy publikujñcy interfejsy API czösto doäñczajñ za
wiele funkcji lub takie funkcje, które tak naprawdö sñ nieodpowiednie. Na
przykäad mieliĈmy do czynienia z publicznymi interfejsami API zawierajñ-
cymi funkcje, które przeznaczone byäy wyäñcznie do uĔytku wewnötrznego
(takie jak tabele kodów wewnötrznych).
Kin Lane, promotor projektantów w firmie Mimeo, twierdzi, Ĕe mniejsza
liczba funkcji bödzie korzystna dla projektu interfejsu API. „Moja rada jest
nastöpujñca: prostsze znaczy lepsze. Usäuga REST, format JSON czy inne
proste i zrozumiaäe usäugi. Nie próbujcie zbytnio komplikowaè interfejsu.
Skoncentrujcie siö na podstawowych komponentach tworzñcych interfejs
API. Zróbcie jedno, ale naprawdö dobrze, a ponadto doäñczcie do tego prostñ
dokumentacjö i przykäadowe kody. Sñ to fundamenty interfejsu API”.
Oprócz oferowania najmniejszego, ale jednoczeĈnie w miarö moĔliwoĈci
najbardziej rozbudowanego zestawu operacji kluczowe znaczenie ma teĔ
okreĈlenie struktury interfejsu API w przystöpny sposób. Jest to ogromna za-
leta interfejsów API, które zgodne sñ z opisanymi dalej wzorcami „pragma-
tycznej” usäugi REST. Tego rodzaju interfejsy API sñ äatwe do opanowania,
poniewaĔ prezentujñ swoje operacje w postaci zrozumiaäych dla czäowieka
identyfikatorów URI, które mogñ byè testowane za pomocñ prostych narzö-
dzi, takich jak przeglñdarka internetowa.
MoĔe siö wydawaè, Ĕe podczas tworzenia interfejsu API nieistotne jest to,
aby cechowaä siö on intuicyjnoĈciñ, äatwoĈciñ obsäugi i elegancjñ. JeĈli interfejs
API zapewnia odpowiedniñ funkcjonalnoĈè, to czy projektanci i tak nie bödñ
z niej korzystaè? MoĔe to mieè sens do momentu pojawienia siö konkurencji
dla interfejsu. Twórcy aplikacji sñ wybredni, zadufani w sobie, a przede
wszystkim dziaäajñ w poĈpiechu. Elegancko zaprojektowany interfejs API,
którego obsäuga sprawi przyjemnoĈè projektantom, zyska zwolenników i za-
dowolonych uĔytkowników w stopniu, na jaki nie pozwolñ dziaäania cechujñ-
ce siö mniejszñ starannoĈciñ.
Nie rób niczego dziwnego
WyróĔniè moĔna takĔe inne aspekty prostoty, które mogñ przyczyniè siö
do uäatwienia adaptacji Twojego interfejsu API. Jednym z czynników powo-
dzenia jest uczestniczenie w spotkaniach, które mogñ byè juĔ znane projek-
tantom.
90
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Jest to szczególnie waĔne w branĔy zabezpieczeþ. Wiele interfejsów API
oferuje niestandardowe lub zäoĔone schematy zabezpieczeþ, które wymagajñ
od projektantów opanowania ich od podstaw, co jest znacznñ przeszkodñ
na drodze do decyzji o adaptacji interfejsu. Zastanów siö nad uĔyciem
powszechnych standardów, takich jak protokóä OAuth bñdĒ innych ogólnie
znanych schematów zabezpieczeþ. Dziöki temu nie tylko moĔesz zwiök-
szyè szanse adaptacji interfejsu, ale teĔ zmniejszyè wäasny (oraz projektantów)
nakäad pracy zwiñzany z projektowaniem.
Mniej znaczy wiýcej
Udane interfejsy API czösto na poczñtku zapewniajñ absolutnie minimalnñ
liczbö funkcji, a póĒniej z upäywem czasu i po uzyskaniu opinii stopniowo
dodawane sñ kolejne.
Po pierwsze, gdy juĔ udostöpniono interfejs API, nie ma odwrotu. Oznacza to,
Ĕe po opublikowaniu funkcjonalnoĈci i zbudowaniu na ich bazie aplikacji
przez projektantów bardzo, ale to bardzo trudno wycofaè takie funkcje.
W przypadku witryny internetowej wymagane jest jedynie ukrycie funkcji.
Ograniczenie funkcjonalnoĈci interfejsu API wiñĔe siö z niemiäñ decyzjñ o dal-
szym wspieraniu funkcji do momentu, aĔ kworum projektantów zacznie
uĔywaè nastöpnej ulepszonej wersji tej funkcji lub jej iteracji. MoĔe to rów-
nieĔ spowodowaè ryzyko problemów z aplikacjami projektantów i wyni-
kajñcego z tego ich gniewu.
Po drugie, caäkiem prawdopodobne jest to, Ĕe klienci bödñ siö domagaè zmiany
rozwoju interfejsu API w innych kierunkach, niĔ wczeĈniej sobie w ogóle
wyobraĔano. Dotyczy to zwäaszcza prywatnych interfejsów API, w przypad-
ku których wewnötrzne zespoäy projektantów majñ bliĔsze relacje z dostawcñ
interfejsów API, a takĔe wiökszy wpäyw. O czymĈ takim nieustannie siö
dowiadujemy. NiezaleĔnie od tego, czy chodzi o strategiö, typ projektanta,
rodzaj aplikacji, czy o konkretnñ funkcjö, która okazuje siö wartoĈciowa, inter-
fejs API czösto rozwija siö w innym kierunku, niĔ przewidywano. W takiej
sytuacji rozpoczöcie od minimalnego poziomu funkcji moĔe daè moĔliwoĈè
najbardziej przejrzystego i najszybszego rozwoju produktu.
Prawdopodobnie istnieje wiöcej powodów niĔ podane, ale ogólnie rzecz bio-
rñc, prawie zawsze dobrym rozwiñzaniem bödzie rozpoczöcie od mniejszej
liczby funkcji i dodawanie kolejnych w razie potrzeby. Jest to zgodne z za-
sadñ, która gäosi, Ĕe mniej znaczy wiöcej.
Kwestie techniczne projektu interfejsów API
_
91
Ukierunkowanie na konkretny segment projektantów
Przed zastanowieniem siö nad sposobem uruchomienia interfejsu API pomyĈl
o tym, kto ma byè jego odbiorcñ i jakie dziaäanie ma zostaè przez niego
podjöte.
Jak w przypadku wszystkich dobrych programów marketingowych kam-
pania marketingowa zwiñzana z interfejsem API moĔe byè znacznie uäa-
twiona przez ustalenie konkretnego segmentu projektantów lub aplikacji,
które majñ zostaè uwzglödnione. UproĈci to doprecyzowanie strategii,
taktyki, zasobów i metody pomiaru skali powodzenia.
Kontaktujñc siö z firmami w trakcie uruchamiania interfejsu API, czösto zada-
jemy nastöpujñce pytanie: „Kim sñ odbiorcy docelowi?”. JeĈli w odpowiedzi
usäyszymy, Ĕe wszyscy, bödziemy zmartwieni. Podobnie jeĈli zadamy py-
tanie: „Jakiego rodzaju aplikacje majñ zostaè zbudowane?”, bödziemy zasmu-
ceni po usäyszeniu, Ĕe chodzi o wszystkie rodzaje.
Z czego to wynika? Tak naprawdö trudno stworzyè interfejs API, który speäni
wymagania kaĔdego moĔliwego elementu oraz przypadku uĔycia. JeĈli
nawet otrzymano by idealny interfejs API, nie jest moĔliwy skuteczny marke-
ting dla tych wszystkich segmentów.
Po czöĈci atrakcyjnoĈè interfejsu API, prywatnego lub publicznego, polega
na tym, Ĕe umoĔliwia on projektantom wprowadzanie innowacji w sposób,
jakiego dostawca interfejsu moĔe nie przewidzieè. Oznacza to, Ĕe podczas
uruchamiania interfejsu waĔne jest okreĈlenie oczekiwaþ odnoĈnie do tego,
jak usäuga bödzie prawdopodobnie uĔywana. Dziöki temu moĔliwe bödzie
zapewnienie interfejsu API, który speäni wymagania dotyczñce przypad-
ków uĔycia. Dla kaĔdego z nich ustal, jacy prawdopodobnie bödñ odbiorcy
docelowi, a nastöpnie projektuj pod ich kñtem.
Po odniesieniu sukcesu w przypadku pierwszego segmentu moĔesz dodaè
nowych partnerów, którzy z kolei umoĔliwiñ rozszerzenie projektu o wspar-
cie ich konkretnych potrzeb. JeĈli uruchamiany jest publiczny interfejs API,
przeprowadĒ analizy dotyczñce demografii segmentów projektantów we-
däug jö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Ĕym stopniu wpäywajñ na sposób funkcjonowania in-
terfejsu API.
92
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Usĥuga REST
RóĔne warianty usäugi REST (Representational State Transfer) to obecnie pre-
ferowana metoda tworzenia interfejsów API. Styl bazujñcy na tej usäudze zo-
staä opracowany w ramach pracy doktorskiej przez Roya Fieldinga, który
byä jednym z twórców protokoäu HTTP.
Zasadniczo Fielding zaproponowaä uĔycie tego protokoäu do komunikacji
miödzy komputerami. W konsekwencji usäuga REST oparta jest na standar-
dzie HTTP. Korzystajñc ze skäadników protokoäu HTTP, usäuga dzieli prze-
strzeþ nazw na zestaw „zasobów” opartych na unikalnych wzorcach
identyfikatorów URI. Ponadto usäuga REST stosuje standardowe metody
protokoäu HTTP (
GET
,
POST
,
PUT
i
DELETE
) do odwzorowywania operacji na
bazie tych „zasobów”. Te standardowe metody dokonujñ odwzorowania
na funkcje create (utwórz), read (odczytaj), update (aktualizuj) i delete (usuþ),
które sñ znane generacjom programistów w postaci skrótu CRUD.
Identyfikatory URI i adresy URL: czym siý różnié?
W Ĉwiecie standardów internetowych identyfikator URI (Uniform Resource
Identifier
) to ogólne odwoäanie do „zasobu” dostöpnego w sieci. MoĔe to
byè bardzo konkretne odwoäanie opisujñce protokóä sieciowy, który ma
zostaè uĔyty do uzyskania dostöpu do odwoäania w sieci, metodö zapew-
niajñcñ ten dostöp oraz miejsce, w którym odwoäanie ma byè szukane. Na
przykäad http://helion.pl/ksiazki/autocad-2014-pl-andrzej-pikon,ac23pl.htm to
identyfikator URI. Identyfikator moĔe byè teĔ 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östo byä
uĔywany do odwoäywania siö do typu identyfikatora URI, który obej-
muje protokóä sieciowy. Z technicznego punktu widzenia takie zastosowanie
jest poprawne, ale w Ĉwiecie standardów internetowych miaäo miejsce
stopniowe przechodzenie do wykorzystywania skrótu URI w przypadku
takich odwoäaþ. W niniejszej ksiñĔce bödziemy siö trzymaè takiej definicji
i konsekwentnie uĔywaè terminu URI.
W usäudze REST identyfikator URI w unikalny sposób odwoäuje siö do za-
sobu, obiektu lub kolekcji obiektów. Fielding sformalizowaä tö strukturö
i zapewniä jñ w postaci prostej metody projektowania interfejsu API, który
bödzie dziaäaè w przypadku kaĔdego komputera bñdĒ systemu operacyj-
nego. Na przykäad program na komputerze A wymaga sprawdzenia listy
Kwestie techniczne projektu interfejsów API
_
93
klientów. Dysponuje on informacjñ o istnieniu na komputerze zasobu zdefi-
niowanego przez identyfikator URI, w którym moĔe uzyskaè dostöp do listy.
Wszystkie dziaäania, które mogñ byè realizowane w odniesieniu do „klienta”
obiektu, takie jak usuwanie lub dodawanie, sñ dostöpne za poĈrednictwem
odsyäaczy i reprezentowane jako dane XML (zgodnie z pierwotnñ propozycjñ
Fieldinga dane XML i hipertekst sñ kluczowymi elementami usäugi REST).
Obecnie prawie kaĔda platforma informatyczna moĔe komunikowaè siö
z serwerem HTTP. Najlepsze interfejsy API bazujñce na usäudze REST potrze-
bujñ do dziaäania niewiele wiöcej niĔ podstawowej obsäugi protokoäu
HTTP. Porównaj to z wczeĈniejszymi rozwiñzaniami, takimi jak SOAP, które
do poäñczenia siö z serwerem wymagajñ zäoĔonego stosu klienta.
Niestety, podobnie jak kaĔde zäoĔone zagadnienie informatyczne termin REST
powoduje niejasnoĈci i dyskusjö. Czasami uĔywany jest niewäaĈciwie, a cza-
sami zwolennicy usäugi REST zbytnio przesadzajñ z budowaniem Ĉwia-
domoĈci tego, Ĕe niepoprawne jest stosowanie go w mniej czystej formie.
W tym miejscu chcemy siö zajñè zwiñzanymi z tym wñtpliwoĈciami.
Usĥuga REST w czystej formie
W swojej najczystszej formie usäuga REST jest zgodna z wytycznymi zawar-
tymi w pracy doktorskiej Fieldinga, a takĔe w nowszych pracach i wpisach
zamieszczonych na blogu. Centralne znaczenie dla stylu usäugi REST ma
pojöcie kryjñce siö pod skrótem HATEOAS (Hypermedia as the Engine of Appli-
cation State
).
Interfejs API, który przestrzega reguä HATEOAS, identyfikuje siö sam za
pomocñ kontraktu bardzo róĔniñcego siö od kontraktów innych typów
interfejsów API. Zamiast definiowania listy dziaäaþ, jakie klient moĔe zre-
alizowaè w dokumencie statycznym, taki interfejs API wymaga od uĔywajñ-
cego go klienta wykrycia funkcji zapewnianych przez interfejs. Klient, który
korzysta z interfejsu opartego na usäudze REST, äñczy siö najpierw z ser-
werem i wykonuje metodö
GET
dla gäównego identyfikatora URI. Z kolei
ten identyfikator zwraca listö dodatkowych identyfikatorów URI, które
mogñ byè uĔywane na potrzeby dodatkowych operacji itp.
Inaczej mówiñc, klient interfejsu API REST realizuje nastöpujñce czynnoĈci:
GET
http://api.myapi.com/
Metoda zwraca dokument „powitalny”, który zawiera listö dodatko-
wych identyfikatorów URI.
94
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
GET
http://api.myapi.com/customers
Klient stwierdza, Ĕe jeden z odsyäaczy w dokumencie „powitalnym”
opisuje sposób uzyskania listy klientów, dlatego wywoäuje ten identy-
fikator URI (jeĈli odsyäacz ten okazaä siö niepoprawny, klient nie po-
winien go uĔywaè — technologia HATEOAS wyklucza trwaäe umiesz-
czanie identyfikatorów URI po stronie klienta).
POST
http://api.myapi.com/customers
Klient stwierdza, Ĕe metoda
GET
z poprzedniego kroku zwróciäa inny
odsyäacz do identyfikatora URI, który moĔe byè stosowany do dodania
nowego klienta, dlatego klient wywoäuje ten odsyäacz.
Klient nie zmienia siö
Rzecz w tym, aby nigdy nie umieszczaè identyfikatora URI na trwaäe,
lecz by wykrywaè go za pomocñ interfejsu API.
Innymi säowy, klient, który przestrzega wszystkich reguä usäugi REST, za-
chowuje siö dokäadnie tak jak czäowiek przeglñdajñcy witrynö internetowñ,
korzystajñc wyäñcznie z wyĈwietlanych odsyäaczy (klient ignorujñcy wytyczne
HATEOAS zachowuje siö z kolei jak uĔytkownik, który tworzy zakäadki
dla konkretnych stron znajdujñcych siö gäöboko w strukturze identyfikato-
rów URI witryny; w pewnym momencie takie zakäadki przestanñ siö
sprawdzaè).
Klienty i serwery zgodne z reguäami HATEOAS sñ rzeczywiĈcie skalowalne
i rozszerzalne. Serwer moĔe zmieniè postaè i funkcjonalnoĈè interfejsu API,
a nawet usunñè okreĈlone funkcje bez negatywnego wpäywu na klienta,
poniewaĔ zostaä on tak zbudowany, aby dynamicznie dostosowywaä siö
do zmian po stronie serwera.
Pragmatyczna usĥuga REST
JeĈli w przeszäoĈci korzystano z interfejsów API REST, treĈè wczeĈniejszego
punktu moĔe brzmieè obco. Prawdopodobnie uĔywano interfejsów API
REST, które wcale nie dziaäajñ w sposób opisany w tym punkcie. Byè moĔe
zamiast stosowania jedynie odsyäaczy zwróconych przez serwer przyzwy-
czajono siö do trwaäego wstawiania identyfikatorów URI. Czasami ma to
miejsce, poniewaĔ tak zwane interfejsy API REST wcale nie bazujñ na usäudze
REST, lecz po prostu jako metodö komunikacji wykorzystujñ format JSON
lub XML za poĈrednictwem protokoäu HTTP (wkrótce zostanie opisany
taki interfejs API).
Kwestie techniczne projektu interfejsów API
_
95
CzöĈciej jednak jest tak, gdyĔ interfejsy API byäy Ĉwiadomie tworzone
w innym celu. Sñ one zgodne z reguäami REST, lecz nie wszystkimi. Takie in-
terfejsy API sñ äatwe do opanowania i obsäugi, a ponadto reprezentujñ wiök-
szoĈè publicznych interfejsów. W odniesieniu do tych interfejsów API bö-
dziemy uĔywaè terminu pragmatycznej usäugi REST.
Dlaczego wiele interfejsów API zostaäo zaprojektowanych w taki „pragma-
tyczny” sposób? Po czöĈci wynika to z faktu, Ĕe zasady HATEOAS sta-
wiajñ programiĈcie po stronie klienta poprzeczkö bardzo wysoko. Progra-
mista, który nieumyĈlnie lub celowo trwale umieĈci ĈcieĔkö identyfikatora
URI w aplikacji, moĔe w przyszäoĈci doznaè szoku, a zespóä tworzñcy in-
terfejs API po stronie serwera moĔe po prostu poinformowaè klienta o braku
moĔliwoĈci zapewnienia zgodnoĈci ze specyfikacjñ.
Takie interfejsy API mogñ teĔ byè projektowane w ten sposób, gdyĔ nowocze-
sna technologia zwiñzana z interfejsami API (obejmujñca uĔycie serwerów
mediacji miödzy klientem a serwerami, które udostöpniajñ interfejsy API
umoĔliwiajñce ich dostawcom dynamiczne ponowne zapisywanie identy-
fikatorów URI i treĈci) sprawia, Ĕe bardziej funkcjonalne jest utrzymywanie
spójnej struktury identyfikatorów URI.
Choè teoretycznie HATEOAS to dobra metoda w przypadku projektowania
interfejsu API, w praktyce moĔe nie mieè zastosowania. WaĔne jest uwzglöd-
nienie odbiorców interfejsu API i ich moĔliwych metod budowania aplikacji
bazujñcych na interfejsie, a takĔe wziöcie tego pod uwagö przy podejmowaniu
decyzji projektowych. W niektórych sytuacjach HATEOAS moĔe nie byè
wäaĈciwym wyborem.
Zasady pragmatycznej usĥugi REST
W wariancie pragmatycznym usäugi REST wykorzystywane sñ jej najlepsze
elementy. W tym przypadku zdano sobie sprawö z tego, Ĕe programistom
zaleĔy na jak najszybszym zaznajomieniu siö z moĔliwoĈciami interfejsu
API, a ponadto chcñ z nich skorzystaè bez koniecznoĈci pisania duĔej iloĈci
dodatkowego kodu.
Proponujemy nastöpujñce zasady pragmatycznej usäugi REST:
Identyfikatory URI sñ istotne
Dobrze opracowany wzorzec identyfikatorów URI powoduje, Ĕe inter-
fejs API jest äatwy do zastosowania, poznania i rozszerzenia, tak jak
ma to miejsce w przypadku starannie zaprojektowanego interfejsu API
powiñzanego z tradycyjnym jözykiem programowania. W usäudze
REST w czystej postaci reguäa ta jest zastöpowana przez HATEOAS.
96
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Parametry sñ istotne
UĔyj standardowego i äatwego do zidentyfikowania zestawu opcjonal-
nych operacji dla kaĔdego wywoäania interfejsu API.
Format danych jest istotny
Spraw, aby programiĈci bez trudu mogli zrozumieè, jakiego rodzaju
danych oczekuje interfejs API, jakiego typu dane zostanñ przez niego
zwrócone, a takĔe jak to zmieniè.
Kody powrotu sñ istotne
UĔyj kodu 404, gdy na przykäad ĈcieĔka nie prowadzi do rzeczywistego
obiektu lub kolekcji, a nie zwracaj ogólnego kodu bäödu, który wymaga
wäaĈciwego zinterpretowania przez uĔytkownika.
Wszystko inne powinno byè ukryte
Informacje o zabezpieczeniach, ograniczaniu transferu, routingu itp.
mogñ i powinny byè ukrywane w nagäówkach protokoäu HTTP.
Ustal przejrzyste konwencje oznaczania wersji
Czy na przykäad identyfikator URI powinien zawieraè numer wersji
albo czy powinien on byè parametrem? Jaka wersja powinna zostaè do-
starczona w przypadku niespeänienia dowolnego z tych warunków?
OczywiĈcie w tym przypadku przyjmuje siö, Ĕe Twój interfejs API
w ogóle korzysta z wersji.
W szczególnoĈci powyĔsze zasady sugerujñ nastöpujñce reguäy dotyczñce
identyfikatorów URI:
x
ćcieĔki URI odwoäujñce siö do kolekcji obiektów powinny uwzglöd-
niaè rzeczownik w liczbie mnogiej, na przykäad
/klienci
, aby odnosiè
siö do zbioru wszystkich klientów.
x
ćcieĔki URI odwoäujñce siö do pojedynczego obiektu powinny zawie-
raè rzeczownik w liczbie pojedynczej, po którym nastöpuje unikalny
klucz podstawowy. Na przykäad
/klienci/Bogdan
odwoäuje siö do klienta
z podstawowym identyfikatorem Bogdan, a
/konta/123456
odnosi siö
do konta o numerze 123456.
x
Poprawne jest rozpoczöcie identyfikatora URI od ĈcieĔki identyfikujñ-
cej, takiej jak ĈcieĔka zawierajñca numer wersji lub informacje o Ĉro-
dowisku.
x
Po ĈcieĔce identyfikujñcej w identyfikatorze URI nie powinno siö znaleĒè
nic innego, z wyjñtkiem kolekcji i obiektów.
Kwestie techniczne projektu interfejsów API
_
97
x
Zestaw standardowych parametrów zapytania powinien byè uĔywany
dla kolekcji w celu umoĔliwienia elementowi wywoäujñcemu kontro-
lowania tego, jaka czöĈè kolekcji zostanie udostöpniona. Na przykäad
parametr
count
pozwala okreĈliè liczbö obiektów, które zostanñ zwró-
cone z duĔej kolekcji, parametr
start
säuĔy do ustalenia poczñtkowego
miejsca liczenia obiektów, a parametr
q
reprezentuje ogólne wyszuki-
wanie w dowolnej formie obejmujñce kolekcjö obiektów.
Sugerujemy równieĔ nastöpujñce reguäy dotyczñce obiektów:
x
Pojedyncze obiekty powinny obsäugiwaè metodö
GET
dla odczytu,
metodö
PUT
dla aktualizacji i metodö
DELETE
dla usuwania.
x
Obiekty kolekcji powinny obsäugiwaè metodö
GET
w celu ponownego
wczytania caäoĈci lub czöĈci kolekcji, a takĔe metodö
POST
, aby dodaè
nowy obiekt do kolekcji.
x
Pojedyncze obiekty mogñ obsäugiwaè metodö
POST
w celu zapewnienia
moĔliwoĈci zmiany stanu. Za pomocñ tej metody moĔesz na przykäad
wysäaè nowy dokument JSON bñdĒ XML do obiektu w celu zmiany
okreĈlonych pól albo wywoäaè zmianö stanu lub dziaäanie bez zastö-
powania caäego obiektu.
Przykĥad: projektowanie z wykorzystaniem
pragmatycznej usĥugi REST
W tabeli 5.1 pokazano interfejs API koszyka zakupów, który nie prze-
strzega konwencji usäugi REST w czystej postaci. Interfejs nie jest zgodny
ani z czystym, ani z pragmatycznym wariantem usäugi REST.
Tabela 5.1. NiewäaĈciwa droga do usäugi REST
Zadanie
Operacja
Identyfikator URI
Umieszczanie nowego
produktu w koszyku
POST
http://api.zakupy.com/WstawianieNowegoProduktu
Usuwanie produktu
z koszyka
POST
http://api.zakupy.com/UsuwanieProduktu
Wyļwietlanie zawartoļci
koszyka
GET
http://api.zakupy.com/ZawartoscKoszyka?Identyfikator
´
koszyka=X
Pobieranie produktu
w koszyku
GET
http://api.zakupy.com/WyswietlanieProduktu?Identyfikator
´
koszyka=X&identyfikatorproduktu=Y
Usuwanie caĥego koszyka
POST
http://api.zakupy.com/UsuwanieKoszyka
98
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Ten interfejs API nie jest trudny w uĔyciu, ale konieczne jest opanowanie
poszczególnych operacji. MoĔe to byè käopotliwe, jeĈli istnieje wiele opera-
cji lub interfejs API siö rozwija. WyobraĒ sobie, co by byäo, gdyby oprócz
koszyka pojawiäo siö 50 innych typów obiektów, a wraz z nimi caäy zestaw
operacji. Z tego powodu opracowana dokumentacja interfejsu API byäaby
obszerna, a ponadto wymagaäaby przeszukiwania dla kaĔdego nowego
wywoäania dotyczñcego interfejsu. Projektant moĔe byè na przykäad zmu-
szony do sprawdzenia, czy operacja
InsertNewItem
umieszcza jedynie pro-
dukt w koszyku, natomiast operacja
InsertNewItemIntoWishlist
musi zostaè
uĔyta dla listy Ĕyczeþ klienta i tak dalej aĔ do znudzenia.
ãatwiejszy do opanowania jest koszyk zakupów bazujñcy na wariancie
pragmatycznym usäugi REST, który zaprezentowano w tabeli 5.2.
Tabela 5.2. Koszyk zakupów bazujñcy na wariancie pragmatycznym usäugi REST
Zadanie
Operacja
Identyfikator URI
Umieszczanie nowego
produktu w koszyku
POST
http://api.zakupy.com/koszyk/Nazwakoszyka
Usuwanie produktu
z koszyka
DELETE
http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/
Nazwaproduktu
Wyļwietlanie
zawartoļci koszyka
GET
http://api.zakupy.com/koszyk/Nazwakoszyka
Pobieranie produktu
w koszyku
GET
http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/
Nazwaproduktu
Zastýpowanie
produktu w caĥoļci
PUT
http://api.zakupy.com/koszyk/Nazwakoszyka/produkt/
Nazwaproduktu
Usuwanie caĥego
koszyka
DELETE
http://api.zakupy.com/koszyk/Nazwakoszyka
PowyĔszy zestaw wzorców identyfikatorów URI uäatwia rozszerzanie
interfejsu API za pomocñ prostych sposobów. Co na przykäad bödzie, jeĈli
w dowolnym momencie bödñ miaäy zostaè wyĈwietlone wszystkie koszyki
w systemie? Odpowiednie parametry zostanñ dodane do identyfikatora URI
http://api.zakupy.com/koszyki
za poĈrednictwem metody
GET
protokoäu HTTP.
Parametry zapytania w dalszym ciñgu peäniñ waĔnñ funkcjö, czyli umoĔli-
wiajñ podanie dodatkowych opcji. WyobraĒ sobie na przykäad bardzo duĔy
koszyk zakupów, dla którego wyniki majñ byè stronicowane. Aby przyj-
rzeè siö produktom o numerach od 20 do 29, moĔesz uĔyè identyfikatora URI
podobnego do nastöpujñcego: http://api.zakupy.com/koszyk/Nazwakoszyka?start=
´
20&count=10
.
Kwestie techniczne projektu interfejsów API
_
99
Czasami usĥuga REST wymaga „odpoczynku”
Usäuga REST to znakomity sposób zdefiniowania interfejsu API, który jest
prosty do opanowania i rozwijania. Jednak uĔycie tylko usäugi REST nie
sprawi, Ĕe interfejs API bödzie äatwy do nauczenia i wykorzystania, a po-
nadto dziöki temu nie stanie siö on automatycznie efektywny. Na przykäad
interfejsy API REST czösto sñ projektowane do obsäugi Ĕñdaþ w bardzo
precyzyjny sposób, co powoduje pojawienie siö wielu róĔnych zasobów,
które przetwarzajñ specyficzne typy Ĕñdaþ. W rezultacie do zbudowania po-
jedynczej strony na urzñdzeniu przenoĈnym moĔe byè potrzebnych wiele
osobnych Ĕñdaþ interfejsu API. PoniewaĔ kaĔde takie Ĕñdanie pochodzñce
z urzñdzenia przenoĈnego zajmuje wiele czasu i wpäywa na wykorzysta-
nie energii baterii, drobiazgowy interfejs API zmniejsza wydajnoĈè i ma
wpäyw na komfort pracy uĔytkownika.
MoĔliwe jest jednak zaprojektowanie efektywniejszego interfejsu API bez
caäkowitego rezygnowania z usäugi REST. Na przykäad mogñ zostaè utwo-
rzone metazasoby wyĔszego poziomu, które w ramach jednego zasobu äñ-
czñ kilka zasobów niĔszego poziomu. Inna metoda jest okreĈlana mianem
Ĕñdania masowego. Aby na przykäad pobraè jednoczeĈnie 10 elementów
z interfejsu API REST, wyĈlij jedno Ĕñdanie HTTP zawierajñce listö identyfi-
katorów URI, a nastöpnie zwróè kolejno wszystkie odpowiedzi tak, jakby
kaĔda z ich dziesiöciu zostaäa wygenerowana osobno.
Porównanie formatów XML i JSON
Poczñtkowo w przypadku interfejsów API REST faktycznym standardem
byä format XML. Nawet obecnie istnieje wiele sensownych scenariuszy,
w których format XML jest wäaĈciwym wyborem. Jako model danych format
ten zostaä uĔyty do stworzenia standardowych skäadni opisujñcych niektó-
re z najbardziej zäoĔonych zbiorów danych na Ĉwiecie, obejmujñcych kon-
trakty terminowe i polisy ubezpieczeniowe. Twórcy kodu XML mogñ de-
finiowaè skäadniö umoĔliwiajñcñ pobieranie modeli informacji z róĔnych
obszarów, äñczenia ich w jeden zäoĔony dokument bez obaw, Ĕe wystñpi
miödzy nimi konflikt, sprawdzania poprawnoĈci caäoĈci za pomocñ standar-
dowej technologii oraz transformowania i edytowania z wykorzystaniem
zaawansowanych narzödzi. Firmy z branĔ, które wymagajñ tak duĔych
moĔliwoĈci, naprawdö nie mogñ siö obejĈè bez formatu XML.
WiökszoĈè interfejsów API ciñgle korzysta z doĈè prostych jözyków progra-
mowania, dlatego format JSON (JavaScript Object Notation) bödzie znacznie
äatwiejszy w uĔyciu dla programistów po obu stronach interfejsu API.
100
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Format JSON zostaä opracowany przez Douglasa Crockforda, czyli jednñ
z osób zwiñzanych z poczñtkami jözyka JavaScript. Crockford zdecydowaä
siö na stworzenie jözyka definicji danych obejmujñcego niewielki podzbiór
elementów jözyka JavaScript, który wypeänia lukö miödzy obiektami jözy-
ków programowania i technologiami internetowymi. Zapewniajñc äatwoĈè
analizy i translacji, format JSON staä siö popularnñ platformñ dla interfej-
sów API, gdyĔ bez trudu moĔe siö komunikowaè z serwisami interneto-
wymi i aplikacjami dla urzñdzeþ przenoĈnych, które zwykle sñ tworzone
za pomocñ jözyka JavaScript. Ponadto format JSON jest znacznie zwiöĒlej-
szy niĔ format XML. Od momentu pojawienia siö formatu JSON opracowa-
no analizatory skäadni i generatory JSON dla wiökszoĈci jözyków progra-
mowania. Obecnie obsäuga formatu JSON stanowi standardowy element
wielu Ĉrodowisk. PoniewaĔ format JSON zostaä zaprojektowany jako pod-
zbiór jözyka JavaScript, obiekty JSON z äatwoĈciñ mogñ byè przeksztaäcane
w obiekty wiökszoĈci jözyków programowania bez koniecznoĈci dodatkowe-
go analizowania kodu przez programistö. Inaczej sytuacja przedstawia siö
w przypadku formatu XML, który oferuje zäoĔony i bogaty w moĔliwoĈci
model danych, zmuszajñc programistów do konwersji nawet niewielkich
dokumentów XML do postaci obiektu i odwrotnie. Format XML zwiöksza
równieĔ zäoĔonoĈè mechanizmów analizowania skäadni, wprowadzajñc
przestrzenie nazw, atrybuty, warianty kodowania tekstu itp.
Wiöcej informacji o usäudze REST i formacie JSON
TreĈè oryginalnej rozprawy dotyczñcej usäugi REST dostöpna jest pod
adresem http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm.
Specyfikacjö formatu JSON moĔna znaleĒè pod adresem http://json.org/.
Kontrola wersji i projekt interfejsu API
Decyzja dotyczñca tego, czy interfejs API ma mieè numer wersji, czy ma
byè pozbawiony wersji, stanowi waĔnñ kwestiö projektowñ, poniewaĔ
aplikacje budowane na bazie interfejsu zaleĔñ od okreĈlonych funkcji
dziaäajñcych w konkretny sposób. Oznacza to, Ĕe interfejs API jest „ucieleĈnie-
niem” kontraktu miödzy organizacjñ publikujñcñ a projektantem. W miarö
pojawiania siö nowych wersji interfejsu API kontrakt ten powinien pozo-
staè w niezmienionej postaci. Fakt ten wymaga rozwaĔenia w kontekĈcie
ciñgäych Ĕñdaþ uĔytkowników dotyczñcych aktualizacji funkcji oraz we-
wnötrznych moĔliwoĈci firmy i chöci wspierania na bieĔñco starszych zesta-
wów funkcji. Zespoäy projektujñce interfejsy API sñ zwykle niewielkie i majñ
ograniczone moĔliwoĈci obsäugiwania nowych wersji. Projektanci nieustannie
Kwestie techniczne projektu interfejsów API
_ 101
oczekujñ nowszych i bardziej rozbudowanych wersji interfejsu API, nato-
miast uĔytkownicy koþcowi spodziewajñ siö ulepszanych aplikacji. Rze-
czywistoĈè jest taka, Ĕe zespóä projektowy moĔe jednoczeĈnie obsäugiwaè
tylko kilka wersji.
Istnieje wiele róĔnych metod rozwiñzania tych problemów. Chcemy za-
proponowaè jednñ z nich, która skäada siö z trzech nastöpujñcych drobnych
kroków:
x
W jakimĈ miejscu, które jest widoczne dla kaĔdego klienta lub wywo-
äania interfejsu API, doäñcz wersjö 1. (przewaĔnie informacja ta jest
uwzglödniana w ĈcieĔce identyfikatora URI).
x
KaĔdorazowo po zmodyfikowaniu interfejsu API za wszelkñ cenö próbuj
unikaè ciñgäego zwiökszania numeru wersji aĔ do wersji 2.
x
RozwaĔ pominiöcie informacji o wersji w identyfikatorze URI bñdĒ
parametrze, aby wskazaè interfejsowi API, Ĕe ma skorzystaè z pierwszej
lub najnowszej wersji.
W przypadku tego rozwiñzania identyfikowane sñ dwie kwestie. Po pierwsze,
jest to koniecznoĈè intensywnej pracy w celu zachowania w niezmienionej
postaci kontraktu interfejsu API. Kontrakt moĔe byè modyfikowany w spo-
sób, który nie wpäywa na dziaäanie istniejñcych aplikacji. Aby jednak wpro-
wadziè zmianö, która moĔe spowodowaè, Ĕe aplikacje przestanñ dziaäaè,
niezbödne bödzie jawne zaplanowanie takiej sytuacji. Po drugie, jest to
zdanie sobie sprawy z tego, Ĕe czasami w okresie dostöpnoĈci interfejsu
API konieczne okaĔe siö przyznanie do popeänienia bäödu, co bödzie wyma-
gaè rozpoczöcia od nowa z wykorzystaniem wersji o numerze 2.
Takie rozwiñzanie zapewnia teĔ elastycznoĈè zmiany kontroli wersji, gdy za-
istnieje taka potrzeba. JeĈli jednak projektant nie zmieni numeru wersji w swoim
kodzie, jego Ĕñdania w dalszym ciñgu bödñ obsäugiwane bez zakäóceþ.
Alternatywnie dla interfejsu API moĔesz opracowywaè strategiö dotyczñcñ
wersji, a ponadto rozwaĔaè nastöpujñce kwestie:
x
Czy numer wersji zäoĔony jest z trzech lub czterech cyfr?
x
Czy numer wersji zmienia siö kaĔdorazowo po wprowadzeniu nowej
wersji interfejsu API?
x
Czy w okresie istnienia interfejsu API albo firmy numer wersji bödzie
mieè kiedykolwiek postaè dwucyfrowñ?
x
Czy numer wersji oparty jest na dacie ostatniej modyfikacji interfejsu
API?
102
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
JeĈli rozpatrujesz powyĔsze zagadnienia, prawdopodobnie dokonujesz
niewäaĈciwego wyboru. Takie rozwiñzania mogñ siö sprawdziè w przypadku
aplikacji lub systemów, które majñ postaè bardzo maäej, kontrolowanej
dystrybucji. W odniesieniu do publicznych i prywatnych interfejsów API
mogñ jednakĔe spowodowaè mnóstwo problemów.
Zapamiötaj, Ĕe interfejs API to kontrakt. Publikujñc interfejs API
i tworzñc jego dokumentacjö, skäadasz równieĔ obietnicö tego, Ĕe
bez wczeĈniejszego powiadomienia nie spowodujesz, iĔ istniejñce
aplikacje przestanñ dziaäaè.
Numer wersji przekazuje zasadniczo nastöpujñcñ informacjö: „Proszö za-
koþczyè korzystanie ze starego kontraktu i przejĈè na nowy”. Informuje on
teĔ jednak o tym, Ĕe stary kontrakt jest nadal waĔny. Opublikowanie nowej
wersji kaĔdorazowo bödzie wymagaè nakäadu pracy od osób uĔywajñcych
interfejsu API, co nie bödzie dla nich powodem do zadowolenia. Bez wñt-
pienia czöĈè z tych osób nigdy nie przejdzie na nowñ wersjö, a to bödzie
oznaczaè, Ĕe ich aplikacje przestanñ dziaäaè, gdy w koþcu wyäñczysz ob-
säugö starej wersji interfejsu API.
Z kolei im däuĔej moĔesz korzystaè ze zautomatyzowanego testowania re-
gresyjnego w celu upewnienia siö, Ĕe nigdy nie byäo konieczne zwiöksza-
nia numeru wersji, tym mniej czasu poĈwiöcisz na omawianie z klientami
kwestii kontroli wersji. Oznacza to takĔe, Ĕe niezbödne bödzie wspieranie
starszego kodu i zautomatyzowanych testów do momentu zaprzestania
obsäugi starszej wersji.
Zastanawiajñc siö nad sposobem obsäugi kontroli wersji, spróbuj odpo-
wiedzieè na nastöpujñce pytania:
x
Co siö stanie ze starszymi wersjami?
x
Co siö stanie z aplikacjami zaprojektowanymi na bazie starszych wersji?
x
Czy nowe wersje obsäugujñ wszystkie funkcje starszych aplikacji albo
czy klienci uĔywajñcy interfejsu API muszñ zaktualizowaè swoje apli-
kacje, aby mieè moĔliwoĈè korzystania z nowszych wersji?
x
Czy dysponujesz planem minimalizowania liczby sytuacji, w których
prosisz projektantów o aktualizowanie lub zmienianie wersji?
x
Ile moĔesz utworzyè wyjñtkowych wersji dla „szczególnych” partnerów?
Jaki jest koszt obsäugi zwiñzany z takñ decyzjñ?
Strategia opracowywana pod kñtem wycofywania starych wersji interfejsu
API bödzie mieè wpäyw na strategiö dotyczñcñ kontroli wersji. UĔytkownicy
interfejsu bödñ bardziej zadowoleni, jeĈli udostöpnisz przejrzyste reguäy
Kwestie techniczne projektu interfejsów API
_ 103
okreĈlajñce, przez jaki czas bödzie wspierana przestarzaäa wersja, zamiast
przesäania jedynie tydzieþ wczeĈniej powiadomienia o zamiarze wyäñczenia
starej wersji lub wprowadzenia wielu zmian. WczeĈniejsze przedstawienie
takiej strategii wycofywania wersji przyczyni siö do zdobycia zaufania i za-
chöci do adaptacji interfejsu API.
Godne uwagi jest to, Ĕe strategie zwiñzane z kontrolñ wersji bödñ inne
dla publicznych i inne dla prywatnych interfejsów API. W przypadku tych
pierwszych spoäecznoĈè projektantów to prawdopodobnie duĔa grupa po-
tencjalnie nieznanych twórców aplikacji. Bardzo trudne moĔe siö okazaè zro-
zumienie ich potrzeb, oczekiwaþ i moĔliwoĈci dostosowania do zmian wpro-
wadzonych w interfejsie API. Jednak w przypadku prywatnych interfejsów
API zespoäy korzystajñce z interfejsu sñ zwykle ze sobñ bliĔej powiñzane,
bardziej przygotowane na dokonywane w nim zmiany, bardziej elastycz-
ne, a czösto motywujñce do rozwijania interfejsu. Projektanci prywatnych
interfejsów API mogñ nie wymagaè wczeĈniej czasu na przygotowanie do
nowych wersji. Mogñ oni nawet wcale nie potrzebowaè wielu wersji.
Zastosowanie warstwy mediacji
Zmiana wersji interfejsu API nie musi byè bolesna dla uĔytkowników lub
uciñĔliwa dla systemów. Technika nazywana mediacjñ moĔe ograniczyè nie-
które trudnoĈci towarzyszñce niezbödnym zmianom wersji. Jest to moĔliwe,
poniewaĔ, tak jak wczeĈniej wspomniano, interfejsy API sñ zwykle oparte
na samoopisujñcych siö formatach danych. Bez uĔycia jakiegokolwiek specjal-
nego kodu warstwa umieszczona miödzy klientem interfejsu API a koþ-
cowym serwerem API moĔe transformowaè kaĔde Ĕñdanie i odpowiedĒ ze
starej do nowej wersji, co nie wymaga wprowadzania Ĕadnych zmian na
serwerze.
W jaki sposób moĔesz udostöpniaè róĔne wersje tego samego interfejsu API
i zarzñdzaè nimi albo dokonywaè „mediacji” (lub transformacji) zawartoĈci
i skäadni interfejsu API?
Alternatywne rozwiñzania obejmujñ:
x
obsäugö wielu interfejsów API (uciñĔliwe);
x
jak najdäuĔsze wstrzymywanie siö z nowñ wersjñ i objöcie klientów mo-
delem typu „jedna wielkoĈè pasuje do wszystkiego” (bardziej uciñĔliwe);
x
zapewnienie moĔliwoĈci mediacji lub warstwy, która pozwala doko-
nywaè transformacji miödzy wäaĈciwoĈciami interfejsu API, takimi jak
protokóä, dane, wersja i dane uwierzytelniajñce.
104
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
UĔycie warstwy mediacji wraz ze strategiñ zamiast logiki biznesowej (wiö-
cej na ten temat napisano w dalszej czöĈci rozdziaäu) moĔe uäatwiè pracö
w przypadku kontroli wersji (a takĔe niektórych innych kluczowych kwestii,
takich jak zabezpieczenia, ograniczenie transferu itp.).
Choè jest to przydatna technika, to jeĈli zmiany powodujñ nowe bñdĒ zmie-
niajñce siö elementy odpowiedzi, mediacja moĔe nie uchroniè skutecznie
projektantów aplikacji przed modyfikacjami w interfejsie API.
Skok na gĥýboké wodý: rezygnacja z wersji
W praktyce wiökszoĈè interfejsów API korzysta z kontroli wersji, aby ochroniè
ich klientów przed rozwijajñcym siö interfejsem API (projektanci nie lubiñ
interfejsów, które caäy czas siö zmieniajñ; dotyczy to nawet tych najbardziej
znanych). Z kolei bardzo äatwo moĔna przesadziè z kontrolñ wersji, na skutek
czego obsäuga powiökszajñcej siö listy wersji moĔe byè bardzo utrudniona
i czasochäonna. Na przykäad interfejs API firmy Netflix obsäuguje telewizory
z technologiñ WiFi, które powiñzane sñ z niezwykle specyficznñ wersjñ te-
go interfejsu. Takie powiñzanie czasami umieszczone jest w oprogramowaniu
sprzötowym telewizora, a ponadto nie umoĔliwia wprowadzania zmian.
OczywiĈcie wiökszoĈè osób kupuje telewizory z zamiarem uĔytkowania
ich przez 7 – 10 lat. Oznacza to, Ĕe interfejs API, do którego odwoäuje siö tele-
wizor, musi pozostaè w niezmienionej postaci przez taki okres. JeĈli w ramach
rozwoju interfejsu API firma Netflix kaĔdego roku bödzie publikowaè jego
nowe wersje, ostatecznie moĔe siö okazaè, Ĕe bödzie wspieraè tuzin lub wiöcej
wersji interfejsu API! Taki model obsäugi jest niemoĔliwy do utrzymania
i z pewnoĈciñ spowoduje wiele przestojów Ĉrodowiska produkcyjnego.
Innym rozwiñzaniem jest dñĔenie do caäkowitego zrezygnowania ze sto-
sowania wersji interfejsu API. Aby to osiñgnñè, wymagana jest duĔa dys-
cyplina i dalekowzrocznoĈè.
Choè trudno podoäaè zwiökszajñcemu siö zapotrzebowaniu, z jakim ma do
czynienia wiökszoĈè interfejsów API, jest to moĔliwe. Ponadto jest to cel warty
osiñgniöcia, poniewaĔ oferuje wiele korzyĈci. WspóäuĔytkowany system
bazowy jest preferowany w przypadku zwiökszajñcej siö liczby odröbnych,
lecz podobnych systemów. Dotyczy to szczególnie interfejsów API uĔy-
wanych przez duĔñ liczbö partnerów dostarczajñcych urzñdzenia, z których
czöĈè moĔe nie zapewniaè moĔliwoĈci aktualizowania. Oznacza to, Ĕe ta-
kie urzñdzenia zawsze mogñ wskazywaè na tö samñ wersjö interfejsu API.
Kwestie techniczne projektu interfejsów API
_ 105
Interfejs API bez wersji organizacji NPR
Od poczñtku swojego pojawienia siö w 2007 r. prywatny interfejs
API organizacji NPR pozbawiony byä wersji. W 2008 r. udostöpniono
interfejs w wersji publicznej, dla którego równieĔ nie zastosowa-
no wersji. Wszystkie aplikacje utworzone na bazie tego interfejsu API
cechujñ siö znakomitñ stabilnoĈciñ. Poza tym w ich przypadku
moĔna mieè pewnoĈè, Ĕe interfejs API bödzie nadal rozwijany bez
negatywnego wpäywu na aplikacje.
Oto kilka kluczowych zasad, o których trzeba pamiötaè przy rozwaĔaniu
tego rozwiñzania:
x
Dodawanie nowych funkcji do interfejsu API nie wymaga zwykle no-
wej wersji. Z tego wzglödu stosuj nastöpujñcñ zasadö: Lepsza jest nie-
kompletnoĈè niĔ niedokäadnoĈè. Zasada ta sugeruje, Ĕe naleĔy zrezy-
gnowaè z funkcji w interfejsie API, jeĈli przewiduje siö spore szanse na
to, iĔ bödñ one wymagaè modyfikacji.
x
JeĔeli to moĔliwe, projekt identyfikatorów URI i formaty odpowiedzi
powinny byè ogólne. Dla przykäadu zamiast zwracania w wyniku
pola o nazwie
prywatny_numer_telefonu
utwórz pole
numer_telefonu
i do-
daj atrybut, który wyszczególnia typ (w tym przypadku byäby to typ
type="dom"
). Sprawi to, Ĕe dodawanie numerów telefonu dla nowej lo-
kalizacji lub usuwanie prywatnego numeru telefonu nie wpäynie na
projekt i strukturö interfejsu API.
x
Istnieje tendencja polegajñca na przypisywaniu interfejsowi API roli
ogólnego potoku dystrybucji, który w równym stopniu speänia cele
wszystkich klientów. ZaleĔnie od wymagaþ uĔytkowników interfejsu
API coĈ takiego moĔe utrudniè utrzymanie stabilnego modelu interfejsu.
JeĈli nakäad pracy zwiñzany z utrzymywaniem logiki biznesowej dla
zbyt wielu urzñdzeþ jest za duĔy, sensowne bödzie utworzenie nie-
standardowych punktów koþcowych API dla poszczególnych urzñdzeþ
(a nawet dla kaĔdego Ĕñdania). Dziöki temu urzñdzenia bödñ trakto-
wane w róĔny sposób, a ponadto moĔliwe bödzie unikniöcie koniecz-
noĈci uĔycia wersji dla podstawowego interfejsu API podczas dodawania
nowych funkcji w celu obsäugi konkretnego urzñdzenia.
x
PrzewaĔnie mniejsze spoäecznoĈci projektantów blisko powiñzane z do-
stawcñ interfejsu API (na przykäad wewnötrzne zespoäy projektantów
tworzñcych oprogramowanie dla urzñdzeþ przenoĈnych) sñ znacznie
„odporniejsze” na zmieniajñcy siö interfejs. Oznacza to, Ĕe przy rozwaĔa-
niu interfejsu API bez wersji kluczowe znaczenie ma okreĈlenie grupy
106
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
docelowej. W przypadku interfejsu API, takiego jak Google Maps, niemal
niemoĔliwe jest wprowadzanie zmian bez kontroli wersji z powodu
ogromnej liczby nieznanych projektantów, którzy z niego korzystajñ.
Zaletñ interfejsu API bez wersji jest to, Ĕe nie jest wymagana obsäuga wielu
wersji systemu lub zapewnianie zgodnoĈci wstecz. Wyzwaniem zwiñzanym
z takim interfejsem jest wymuszanie przez niego wczeĈniejszego rozwaĔenia
w szerszym zakresie moĔliwoĈci adaptacji. Ponadto moĔe byè konieczne
podjöcie niewygodnych decyzji, takich jak wstrzymanie funkcjonalnoĈci, które
mogñ byè przydatne. Obsäuga interfejsu API bez wersji jest czösto äatwiejsza
do uzyskania w przypadku prywatnych interfejsów API niĔ w przypadku
publicznych.
Projektowanie infrastruktury
dla interfejsów API
W tym podrozdziale skoncentrujemy siö na kwestiach projektowych zwiñ-
zanych z infrastrukturñ, które obejmujñ moĔliwoĈè skalowania, buforowanie
i ograniczanie transferu.
Jak duĔa powinna byè infrastruktura interfejsów API? Podstawowa zasada
brzmi: Projektuj pod kñtem wymarzonej grupy odbiorców, ale uwzglöd-
niaj oczekiwane obciñĔenie. W przypadku niewielu programów zwiñzanych
z interfejsami API dzienna liczba Ĕñdaþ w ciñgu nocy zwiöksza siö z zera
do 500 milionów. Nierozsñdne bödzie Ĕñdanie od zarzñdu zapewnienia
duĔego budĔetu, jeĈli wczeĈniejsze poniesienie wysokich kosztów nie jest
uzasadnione ewidentnym przypadkiem biznesowym lub mocnym dowodem
na to, Ĕe interfejs API bödzie wymagaä skalowania. Nawet usäuga Twitter
w poczñtkowym etapie funkcjonowania miaäa wiele problemów ze skalo-
waniem (doprowadziäy one do mnóstwa przestojów), ale byäa ona tak
bardzo fascynujñca i unikalna, Ĕe uĔytkownicy nie narzekali, gdy system
okazaä siö niestabilny.
Centrum danych czy chmura?
Zwiökszajñca siö liczba nowych witryn internetowych i interfejsów API
dziaäa z wykorzystaniem skalowalnej platformy usäugi chmury, którñ najczö-
Ĉciej jest platforma Amazon EC2. W przypadku takiej platformy wielkoĈè
poczñtkowej bazy sprzötowej jest nieistotna, poniewaĔ moĔe ona byè szybko
skalowana w górö lub w dóä stosownie do potrzeb (czasami odbywa siö to
Projektowanie infrastruktury dla interfejsów API
_ 107
dynamicznie, zaleĔnie od sposobu skonfigurowania platformy). WiökszoĈè
dostawców interfejsów API bödzie sobie znakomicie radziè, uruchamiajñc
swoje systemy w usäudze chmury. PrzewaĔajñca liczba najwiökszych do-
stawców interfejsów API (na przykäad Google, Yahoo! i Facebook) rezy-
gnuje z centrów danych i stosuje sprzöt, którym bezpoĈrednio zarzñdza.
Niektóre firmy majñ skonfigurowane centra danych i bardzo specyficzne
wymagania dotyczñce opóĒnienia lub zgodnoĈci z wynikami audytu, które
mogñ zostaè speänione tylko przez zapewnienie fizycznego dostöpu do
sprzötu wykorzystywanego przez interfejs API do dziaäania. W przypadku
opóĒnienia najwiökszy problem wielu dostawców interfejsów API ma
zwiñzek z fizycznñ odlegäoĈciñ miödzy serwerem a klientem. Z tego wäaĈnie
powodu czöĈè dostawców bazuje na sieciach dostarczania treĈci CDN
(Content Delivery Network). W celu poradzenia sobie z opóĒnieniem stosuje
siö równieĔ buforowanie.
Strategie buforowania
Z punktu widzenia systemów szybciej zawsze oznacza lepiej. Buforowanie
moĔe skróciè czasy odpowiedzi. JeĈli interfejs API jest powolny, korzysta-
jñce z niego aplikacje takĔe bödñ dziaäaè wolno. JeĔeli aplikacje nie majñ
duĔej wydajnoĈci, uĔytkownicy koþcowi z wiökszym prawdopodobieþ-
stwem poszukajñ lepszych i szybszych opcji. W Ĉwiecie internetowym däugie
czasy äadowania to jedna z podstawowych przyczyn opuszczania witryn
przez internautów. Nie inaczej sprawa wyglñda w Ĉwiecie urzñdzeþ prze-
noĈnych. Buforowanie to jeden ze sposobów zmniejszenia skali czöĈci pro-
blemów z wydajnoĈciñ.
Pamiötaj o tym, Ĕe obecnie uĔywane platformy interfejsów API sñ zäoĔone
z warstw, z których kaĔda dysponuje pamiöciñ podröcznñ. Warstwa mediacji
interfejsu API moĔe buforowaè gotowe odpowiedzi interfejsu w pobliĔu
„granicy sieci”, a serwer aplikacji moĔe zawieraè warstwö buforujñcñ na
potrzeby odpowiedzi interfejsu oraz warstwö säuĔñcñ do buforowania wy-
ników z bazy danych itp. Sieci CDN, takie jak Akamai, równieĔ peäniñ swojñ
funkcjö. Interfejsy API z treĈciñ czösto bödñ zwracaè odnoĈnik do treĈci,
która z kolei przechowywana jest w sieci CDN.
OczywiĈcie w zaleĔnoĈci od treĈci zmienna jest zäoĔonoĈè buforowania. Strona
z prognozñ pogody moĔe byè buforowana w prosty sposób. Prognozy
rzadko aktualizowane sñ czöĈciej niĔ raz na minutö. Z kolei buforowanie
serwisu Twitter jest znacznie trudniejsze, poniewaĔ kaĔdy uĔytkownik wy-
Ĉwietla inny strumieþ. Infrastruktura tego serwisu zawiera wiele warstw
108
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
buforowania, które dynamicznie dopasowujñ siö do postaci zaĔñdanej
treĈci. Choè w przypadku wpisu w serwisie Twitter dotyczñcego Kanyego
Westa lub Ashtona Kutchera pamiöè podröczna jest utrzymywana przez
däuĔszy czas z powodu liczby osób, które go Ĕñdajñ, dla kaĔdej z tych
gwiazd osie czasu sñ unikalne.
Oto kilka ogólnych rad dotyczñcych buforowania interfejsów API:
Najpierw dokonaj pomiaru
UĔywana infrastruktura rejestrowania informacji bñdĒ analizowania
interfejsów API powinna umoĔliwiè stwierdzenie, jakie wywoäania
interfejsu API sñ najpopularniejsze, a jakie majñ najdäuĔszy czas.
W pierwszej kolejnoĈci zakresem buforowania naleĔy objñè najwolniej-
sze i najczöĈciej uĔywane wywoäania interfejsu API zwracajñce wynik,
który nie zmienia siö zbyt czösto.
Nie zapomnij o uniewaĔnianiu
Najtrudniejszym elementem buforowania nie jest podejmowanie de-
cyzji o tym, co ma byè buforowane, lecz okreĈlenie czasu, przez jaki
proces ten ma trwaè, a takĔe ustalenie momentu uniewaĔnienia bufo-
rowania. W tym przypadku konieczne jest uwaĔne planowanie i testo-
wanie. Czy treĈè w pamiöci podröcznej bödzie uniewaĔniana na pod-
stawie znacznika czasu w odpowiedzi? Czy moĔliwe jest uĔycie staäego
czasu? Czy jedno wywoäanie interfejsu API (na przykäad
PUT
lub
DELETE
)
moĔe uniewaĔniè pamiöè podröcznñ?
Monitoruj dziaäajñcñ pamiöè podröcznñ
Nieefektywna pamiöè podröczna z niskim wskaĒnikiem trafieþ nie
wpäynie pozytywnie na wydajnoĈè, a nawet moĔe jñ pogorszyè.
Doļwiadczenie firmy AccuWeather
w zakresie globalnego dostarczania interfejsu API
Z jakimi problemami miaäa do czynienia firma AccuWeather w procesie
globalnego dostarczania interfejsu API?
Lokalizacja. Interfejs API oferujemy w 37 róĔnych jözykach. Täumaczenie
obejmuje nawet poprawny styl dla konkretnego rynku lokalnego.
WydajnoĈè i czas odpowiedzi to waĔne kwestie dla klientów globalnych.
Ostatnio przekroczyliĈmy miliard wywoäaþ interfejsu API dziennie.
Projektowanie infrastruktury dla interfejsów API
_ 109
Przy globalnym dostarczaniu istotne sñ kwestie zwiñzane z buforowaniem,
a zwäaszcza optymalizowanie pamiöci podröcznej pod kñtem odpowied-
niego poziomu szczegóäowoĈci systemu GPS. Nie jest konieczneponowne
korzystanie z magazynu danych w celu uzyskania danych pogodowych
na przesadnym poziomie szczegóäowoĈci systemu GPS.
Reguäy biznesowe sñ odmienne w róĔnych obszarach geograficznych. Nasza
marka wymaga wäaĈciwego täumaczenia w kaĔdym segmencie (na przy-
käad przedrostek accu- moĔe mieè róĔne znaczenia na rynku lokalnym).
Wyjñtkowym wyzwaniem moĔe byè teĔ wspieranie projektantów z caäego
Ĉwiata. Dokäadamy wszelkich staraþ, aby nasze materiaäy byäy w równym
stopniu przejrzyste dla projektantów posäugujñcych siö róĔnymi jözykami.
Chris Patti, dyrektor ds. technologii, firma AccuWeather
Kontrolowanie ruchu sieciowego generowanego
przez interfejsy API
Ograniczanie transferu to mechanizm kontroli zastosowany przez wäaĈci-
cieli interfejsów API w celu zapobiegniöcia przeciñĔeniu systemu przez
ruch sieciowy zwiñzany z danymi interfejsu API, a takĔe powiñzania wy-
korzystania interfejsu z konkretnymi wynikami biznesowymi. Istniejñ róĔ-
ne podkategorie limitów transferu. Okazuje siö, Ĕe caäe zagadnienie jest
ĈciĈle powiñzane z ogólnym zarzñdzaniem ruchem sieciowym. Wszystkie
dostöpne opcje zostanñ omówione w rozdziale 8.
Zanim jednak przejdziemy do szczegóäów technicznych, waĔne jest wyjaĈnie-
nie, jak ograniczenia transferu na poziomie biznesowym, które sñ okreĈlane
mianem przydziaäów, wpäywajñ na projekt interfejsu API.
Przydziaä to limit transferu, który powiñzuje wynik biznesowy z konkretnñ
liczbñ transakcji. Celem przydziaäu jest utrzymanie strategii biznesowej po-
wiñzanej z wykorzystaniem interfejsu API. Na przykäad w serwisie Twitter
projektanci aplikacji mogñ sprawdzaè swoje osie czasu od 150 do 350 razy
w ciñgu godziny, zaleĔnie od bieĔñcego stanu infrastruktury serwisu. Oso-
by, które przekroczñ ten przydziaä, otrzymajñ komunikat o bäödzie. Czöstym
zastosowaniem przydziaäu jest podziaä projektantów na segmenty, z któ-
rych kaĔdy ma inny przydziaä, a tym samym odmienne powiñzanie z in-
terfejsem API. Powszechnñ sytuacjñ jest na przykäad oferowanie dostöpu
do interfejsu API z niewielkim przydziaäem dowolnemu projektantowi,
który zaäoĔy konto. Aby jednak uzyskaè wyĔszy limit transferu, niezbödna
bödzie dodatkowa weryfikacja, a nawet opäata.
110
_
Rozdziaĥ 5. Kluczowe zasady projektowania interfejsów API
Podobnie jak w przypadku sprzötu i infrastruktury koniecznoĈè zastosowania
przydziaäu ma wiele wspólnego z wäaĈciwoĈciami skalowania i wykorzy-
stania. Pytania przewodnie brzmiñ: „Jak wartoĈciowe sñ moje informacje?
Co siö stanie, gdy interfejs API odniesie ogromny sukces?”. Na przykäad
niektóre interfejsy API z treĈciñ sñ w peäni otwarte, nie Ĕñdajñ Ĕadnego
uwierzytelniania uĔytkowników, dlatego teĔ muszñ byè chronione przed
zbyt duĔym ruchem sieciowym. Serwis Twitter wymaga limitu transferu
z powodu prawdopodobieþstwa tego, Ĕe uĔytkownicy mogñ sprawdzaè
swoje osie czasu 1000 razy na sekundö. Infrastruktura nie jest w stanie przyjñè
tak duĔego ruchu sieciowego.
OczywiĈcie moĔliwe jest zrezygnowanie z przydziaäów. Czasami sñ one
stosowane w sposób karny, przez co usäuga staje siö prawie niezdatna do
uĔycia. Na skutego tego utrudnione staje siö testowanie usäugi. Ostatecznie
projektanci mogñ z niej zrezygnowaè. Zachöcamy do pewnej elastycznoĈci.
Bez wñtpienia transfery zwiökszajñ siö, gdy projektanci testujñ swoje apli-
kacje. Mechanizm obciñĔania opäatñ projektantów za transfery wiöksze niĔ
normalnie moĔe uäatwiè zarzñdzanie takimi Ĕñdaniami.
Nie zapomnij o tym, Ĕe przydziaäy sñ teĔ korzystne w przypadku prywat-
nych interfejsów API (nawet w obszarze chronionym przez korporacyjnñ
zaporö firewall), poniewaĔ mogñ byè pomocne w zmniejszaniu ryzyka. Na
przykäad przedsiöbiorstwo moĔe rozwaĔaè udostöpnienie czöĈci swoich
„klejnotów koronnych” jako interfejsu API, aby przyspieszyè tworzenie przy-
szäych produktów biznesowych. JednakĔe te „klejnoty” bazujñ na kosztownej
i kluczowej dla firmy infrastrukturze. WdraĔajñc przydziaäy, zespóä, który
jest w posiadaniu interfejsu API, ma moĔliwoĈè udostöpnienia treĈci lub
usäugi na potrzeby wprowadzania wewnötrznych innowacji przy jednocze-
snym zmniejszaniu ryzyka wystöpowania wewnötrznych problemów oraz
ograniczaniu zagroĔenia w postaci nieprzyjemnego spotkania z zespoäem
ds. operacyjnych firmy! Inaczej mówiñc, efektywne uĔycie przydziaäów
moĔe pomóc wewnötrznemu zespoäowi rozwijajñcemu interfejs API w za-
pewnieniu przedsiöbiorstwu elastycznoĈci internetu.
193
Skorowidz
A
adres URL, 92
analiza interfejsu API, 160
anatomia portalu projektantów, 179
angaĔowanie projektantów, 184–189
dziaäania niezalecane, 188
dziaäania zalecane, 184
API, Application Programming
Interface, 17
API REST, 93
aplikacja StatPlanet, 28
aplikacje, 42, 48
publiczne, 42
wewnötrzne, 44
architektura SOA, 44
atak, 124
CSS, 128
DoS, 153
AWS, Amazon Web Services, 13
B
B2D, Business-to-Developer, 69
blokowanie skoków, 152
bramy interfejsów API, 155
buforowanie, 107, 155
C
CDN, Content Delivery Network, 155
cel biznesowy, 66
centrum danych, 106
chmura, 106, 157
CRUD, 92
CSS, Cross-Site Scripting, 128
D
definiowanie äaþcucha wartoĈci, 38
dochód poĈredni, 57
dodawanie nowych funkcji, 105
dokumentacja referencyjna, 147
dokumentowanie interfejsu API, 145
DoS, Denial-of-Service, 153
dostawca interfejsu API, 19, 21, 39, 48
dostöp do interfejsu API, 175
dystrybucja danych, 33
E
elastyczne udostöpnianie treĈci, 32
elementy äaþcucha wartoĈci, 41, 48
F
filtrowanie na poziomie
artykuäów, 132
zapytaþ, 132
firma
AccuWeather, 108
Amazon, 13
Cisco, 14
Facebook, 14
Innotas, 35, 167
Netflix, 13, 55
NPR, 14
Salesforce.com, 13, 56
Sears, 70
Twitter, 56
194
_
Skorowidz
format
Google Transit, 33
JSON, 99, 124
XML, 99, 124
G
globalne dostarczanie interfejsu API,
108
GPS, 109
H
hasäa, 116
HATEOAS, 93, 95
I
identyfikacja, 114, 122
identyfikator URI, 92
implementowanie strategii
biznesowej, 192
integracja, 58
integracja z klientami, 34
interfejs API, 17, 20, 23, 31
bez wersji, 105, 106
prywatny, 41
publiczny, 47
J
JSON, JavaScript Object Notation, 99
K
kanaä
poĈredni, 37
RSS, 30
kategoria
PoĈrednie, 61, 63
Pozyskanie treĈci, 64
Projektant dokonuje opäaty, 61, 62
Projektant otrzymuje zapäatö, 61, 62
Wewnötrzny zwrot z inwestycji,
63
klient interfejsu API REST, 93
klucze interfejsu API, 114, 122
kluczowe wskaĒniki wydajnoĈci, 65
kod open source, 23, 157
komfort pracy projektantów, 178
kontrakt, 18
kontrola wersji, 100
kontrolowanie ruchu sieciowego, 109
koszty, 59
KPI, Key Performance Indicator, 65
kwestie prawne, 129
L
liczba funkcji, 90
lojalnoĈè, 163
Ĥ
äaþcuch wartoĈci, 37–39
äatwoĈè
testowania, 87
uĔywania, 87
zrozumienia, 88
M
maskowanie danych, 125
metoda
DELETE, 98
GET, 94, 98
POST, 94, 98
metody
HTTP, 92
uwierzytelniania, 118
metryki, 167
operacyjne, 164
wykorzystania, 161
zwiñzane z efektywnoĈciñ, 166
zwiñzane z wydajnoĈciñ, 166
Skorowidz
_ 195
miara sukcesu, 159
modele
biznesowe interfejsów API, 60, 62
konsumpcji, 26
monitorowanie, 144
motywacje projektantów, 174
N
najlepsze praktyki, 85
nazwy uĔytkowników, 116
niedopracowane umowy SLA, 154
niejednakowe Ĕñdania, 154
niewäaĈciwe uĔycie, 137
niewäaĈciwy interwaä czasowy, 153
O
obsäuga
bram interfejsów API, 157
interfejsu API, 139
metryk, 160
ochrona danych interfejsu API, 126
odpowiedzi, 162
ograniczanie transferu, 148
oprogramowanie open source, 23, 157
organizacja NPR, 78, 86, 130, 169
P
portal projektantów, 181, 182
poziomy dostöpu, 129
pozyskiwanie rynków niszowych, 49
praca projektantów, 178
pragmatyczna usäuga REST, 98
prawa
do nadania innym osobom, 129
dystrybucji treĈci, 129
problemy, 157
problemy operacyjne, 142
procedury
operacyjne, 147
techniczne, 84
proces adaptacji, 173
produkt, 175
program dla projektantów, 174
projekt interfejsu API, 100
projektant, 21, 40, 48, 173
projektowanie
infrastruktury, 106
interfejsów API, 81, 82
pod kñtem
projektantów, 83
uĔytkowników aplikacji, 85
promowanie
innowacji, 50
spoäecznoĈci projektantów, 74,
187
protokóä
OAuth, 118
SSL, 118, 120
prywatny interfejs API, 41
äaþcuch wartoĈci, 41
metody uĔycia, 42
strategie, 71
zagroĔenia, 46
zalety, 45
przydziaä, 149
przygotowywanie strategii
produktów, 65
przypisywanie wäaĈciciela treĈci, 137
publiczny interfejs API, 47
äaþcuch wartoĈci, 47
metody wykorzystania, 48
strategie, 72
zagroĔenia, 52
zalety, 51
zamiana na prywatny, 54
R
rekomendacje technologiczne, 83
relacje z partnerami, 43
REST, Representational State
Transfer, 92
rezygnacja z wersji, 104
196
_
Skorowidz
rodzaje dokumentacji, 147
rola promotor projektantów, 74
role w zespole, 73
rozwijanie metryk, 169
rozwój interfejsów API, 28
RSS, Really Simple Syndication, 30
ruch sieciowy, 109
S
SAML, Security Assertion Markup
Language, 118
schematy zabezpieczeþ, 90
sieci CDN, 155
sieè projektantów, 180
skalowalnoĈè, 154
skalowanie integracji, 34
SLA, Service-Level Agreement, 143
SOA, Service-oriented Architecture,
44
spoäecznoĈè projektantów, 179, 187
sponsor, 69
SSL, Secure Sockets Layer, 118
strategia, 68, 70, 71
biznesowa, 25
buforowania, 107
strona statusu interfejsu API, 141
system
oznaczania praw, 131
zarzñdzania prawami, 132
szyfrowanie, 122
Ļ
ĈwiadomoĈè marki, 137
T
techniki zabezpieczeþ, 112
täumienie, 148, 151
tworzenie
aplikacji publicznych, 42
aplikacji wewnötrznych, 44
äaþcucha wartoĈci, 41, 47
wartoĈci biznesowej, 192
zespoäu, 73
typy
interfejsów API, 21
strategii, 70
U
ulepszanie uwierzytelniania, 120
umowy, 133
umowy SLA, 143, 176
uprawnienia, 132
URL, Uniform Resource Locator, 92
URN, Uniform Resource Name, 92
usäuga REST, 92–99
usäugi AWS, 13
usprawnienie architektury
technicznej, 36
uwierzytelnianie, 116, 120, 122
uwierzytelnianie oparte na sesji, 117
uĔytkownik koþcowy, 21, 40
W
warstwa
filtrowania i praw, 134
mediacji, 103
warunki
biznesowe, 176
uĔytkowania, 133
witryna internetowa, 18, 20
wizja, 66
wäaĈciciel
praw, 130
treĈci, 137
wsparcie operacyjne, 144
wstrzykiwanie kodu SQL, 124
wydajnoĈè, 167
wykrywanie zagroĔeþ, 123
wyodröbnianie wyĈwietlanych
danych, 32
Skorowidz
_ 197
wyĈwietlenia, 162
wzorce wykorzystania, 161
Z
zabezpieczenia, 111
zabezpieczenia interfejsów API, 126
zalecenia, 126
zarzñdzanie
interfejsem API, 139
prawami, 130
problemami, 143
ruchem sieciowym, 148, 152, 154
na poziomie biznesowym, 148
uĔytkownikami, 112, 113
zasady
HATEOAS, 95
pragmatycznej usäugi REST, 95
projektowania, 81
prywatnoĈci, 135
utrzymywania danych, 136
zasoby biznesowe, 39, 41, 48
zastosowanie
prywatnych interfejsów API, 45,
70
warstwy mediacji, 103
zastrzeĔenia, 77, 78
zwiökszanie
innowacji, 58
wartoĈci aplikacji, 58
wartoĈci marki, 49
zasiögu, 50, 56
zwrot z inwestycji, 63
zyski, 59
ś
Ĕñdania, 162
Wyszukiwarka
Podobne podstrony:
Interfejs API Strategia programisty
Interfejs API Strategia programisty
Biblia NLP Wydanie rozszerzone ponad 350 wzorcow metod i strategii programowania neurolingwistyczneg
projekt strategicznaego programu rozwoju firmy ZPW Grajewo S, Projekt strategicznaego programu rozwo
projekt strategicznaego programu rozwoju firmy ZPW Grajewo S, Projekt strategicznaego programu rozwo
Strategie-programy st
projekt strategicznaego programu rozwoju firmy ZPW Grajewo S, Ekonomia, ekonomia
Interfejsy szeregowe, ELEKTRONIKA I PROGRAMOWANIE, Mikroprocesory, programowanie Bascom, AVR,
Biblia NLP Wydanie rozszerzone ponad 350 wzorcow metod i strategii programowania neurolingwistyczneg
Biblia NLP 210 wzorcow metod i strategii programowania neurolingwistycznego wlknlp
Biblia NLP 210 wzorcow metod i strategii programowania neurolingwistycznego wlknlp
Biblia NLP Wydanie rozszerzone ponad 350 wzorcow metod i strategii programowania neurolingwistyczneg
Biblia NLP 210 wzorcow metod i strategii programowania neurolingwistycznego wlknlp
Biblia NLP Wydanie rozszerzone ponad 350 wzorcow metod i strategii programowania neurolingwistyczneg
Polityka gospodarcza a strategia i programowanie
więcej podobnych podstron