Interfejs API Strategia programisty

Tytuł oryginału: APIs: A Strategy Guide

Tłumaczenie: Piotr Pilch

ISBN: 978-83-283-0555-7

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.

Księgarnia internetowa

•

Lubię to! » Nasza społeczność

Spis treļci

Przedmowa ......................................................................................9

1. Możliwoļci interfejsów API .......................................................... 13

Dlaczego napisano tö ksiñĔkö?

Dla kogo przeznaczona jest ta ksiñĔka?

Czym jest interfejs API?

Czym interfejs API róĔni siö od witryny internetowej?

Interfejsy API i witryny internetowe

majñ jednakĔe wiele wspólnego

Kto korzysta z interfejsu API?

Typy interfejsów API

Dlaczego teraz?

2. Interfejsy API jako strategia biznesowa .......................................25

Rozwój interfejsów API

Dlaczego interfejs API moĔe okazaè siö potrzebny?

Potrzebujesz drugiej aplikacji dla urzñdzeþ przenoĈnych

Klienci lub partnerzy pytajñ o interfejs API

Witryna internetowa zaczyna byè uĔywana

do wyodröbniania wyĈwietlanych danych

Wymagasz wiökszej elastycznoĈci

w zakresie udostöpniania treĈci

Istniejñ dane, które majñ zostaè udostöpnione

Konkurencja z branĔy korzysta z interfejsu API

Chcesz umoĔliwiè potencjalnym partnerom poznanie nowoĈci

Wymagasz skalowania integracji z klientami i partnerami

Interfejs API ulepsza architekturö technicznñ

3. Ĥaħcuch wartoļci interfejsu API ................................................... 37

Definiowanie äaþcucha wartoĈci: zadawanie kluczowych pytaþ

Tworzenie äaþcucha wartoĈci prywatnego interfejsu API

Metody uĔycia prywatnego interfejsu API

Zalety prywatnych interfejsów API

ZagroĔenia zwiñzane z prywatnymi interfejsami API

Kup książkę

Poleć książkę

Spis treļci

Tworzenie äaþcucha wartoĈci publicznych interfejsów API

Metody wykorzystania publicznego interfejsu API

Zalety publicznych interfejsów API

ZagroĔenia zwiñ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Ĕywane do wspóäpracy z partnerami

Zwiökszanie zasiögu: wiöcej aplikacji, wiöcej platform

Osiñganie poĈredniego dochodu

Zwiökszanie innowacji we wspóäpracy z partnerami

Zwiökszanie wartoĈci aplikacji poprzez integracjö

Wariant uĔycia po czöĈci darmowy, a po czöĈci päatny

Postrzeganie modeli biznesowych interfejsów API przez firmö

ProgrammableWeb.com

4. Przygotowywanie strategii produktów z interfejsami API .........65

OkreĈlanie jasnego celu biznesowego

OkreĈlenie wizji dotyczñcej interfejsu API

Podstawy strategii dotyczñcej interfejsu API

Interfejsy API wymagajñ sponsora biznesowego

Typy strategii zwiñzanych z interfejsami API

Strategie dotyczñce prywatnych interfejsów API

Strategie dotyczñce publicznych interfejsów API

Tworzenie zespoäu

Promotor projektantów

ZastrzeĔenia dotyczñce interfejsów API

5. Kluczowe zasady projektowania interfejsów API .......................81

Projektowanie interfejsów API dla konkretnych grup odbiorców

Projektowanie pod kñtem projektantów

Projektowanie pod kñtem uĔytkowników aplikacji

Najlepsze praktyki zwiñzane z projektem interfejsów API

OdróĔnij wäasny interfejs API

Zapewnij äatwoĈè testowania i uĔywania interfejsu API

Zapewnij äatwoĈè zrozumienia interfejsu API

Nie rób niczego dziwnego

Mniej znaczy wiöcej

Ukierunkowanie na konkretny segment projektantów

Kup książkę

Poleć książkę

Spis treļci

Kwestie techniczne projektu interfejsów API

Usäuga REST

Przykäad: projektowanie z wykorzystaniem

pragmatycznej usäugi REST

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

Kup książkę

Poleć książkę

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

Kup książkę

Poleć książkę

Spis treļci

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

Spis treļci

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:

projektowanie interfejsu API dla róĔnych grup odbiorców;

zapewnienie przeglñdu kwestii technologicznych;

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.

Kup książkę

Poleć książkę

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þ.

Kup książkę

Poleć książkę

Projektowanie interfejsów API dla konkretnych grup odbiorców

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:

„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).

JSON jako format danych pobieranych i zwracanych przez interfejs

API, gdyĔ upraszcza programistom generowanie danych i korzystanie
z nich.

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

Kup książkę

Poleć książkę

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ñ.

Kup książkę

Poleć książkę

Najlepsze praktyki zwiézane z projektem interfejsów API

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.

Kup książkę

Poleć książkę

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:

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.

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.

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.

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è?

Kup książkę

Poleć książkę

Najlepsze praktyki zwiézane z projektem interfejsów API

Oto kilka moĔliwych sposobów odróĔnienia wäasnego interfejsu API:

Dane sñ unikalne, bardziej kompletne lub dokäadniejsze niĔ w przy-

padku interfejsu konkurencji.

Oferowane jest lepsze wsparcie bñdĒ äatwiejszy proces rejestrowania.

Interfejs API jest solidniejszy, bardziej niezawodny, ciekawszy albo
szybszy niĔ rozwiñzanie alternatywne.

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

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

Najlepsze praktyki zwiézane z projektem interfejsów API

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.

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

Kwestie techniczne projektu interfejsów API

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.

Kup książkę

Poleć książkę

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

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

Kup książkę

Poleć książkę

Kwestie techniczne projektu interfejsów API

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.

Kup książkę

Poleć książkę

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).

Kup książkę

Poleć książkę

Kwestie techniczne projektu interfejsów API

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.

Kup książkę

Poleć książkę

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:

ć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.

ć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.

Poprawne jest rozpoczöcie identyfikatora URI od ĈcieĔki identyfikujñ-
cej, takiej jak ĈcieĔka zawierajñca numer wersji lub informacje o Ĉro-
dowisku.

Po ĈcieĔce identyfikujñcej w identyfikatorze URI nie powinno siö znaleĒè
nic innego, z wyjñtkiem kolekcji i obiektów.

Kup książkę

Poleć książkę

Kwestie techniczne projektu interfejsów API

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

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:

Pojedyncze obiekty powinny obsäugiwaè metodö

GET

dla odczytu,

metodö

PUT

dla aktualizacji i metodö

DELETE

dla usuwania.

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.

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

Kup książkę

Poleć książkę

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

Kup książkę

Poleć książkę

Kwestie techniczne projektu interfejsów API

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.

Kup książkę

Poleć książkę

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

Kup książkę

Poleć książkę

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:

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).

KaĔdorazowo po zmodyfikowaniu interfejsu API za wszelkñ cenö próbuj
unikaè ciñgäego zwiökszania numeru wersji aĔ do wersji 2.

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:

Czy numer wersji zäoĔony jest z trzech lub czterech cyfr?

Czy numer wersji zmienia siö kaĔdorazowo po wprowadzeniu nowej
wersji interfejsu API?

Czy w okresie istnienia interfejsu API albo firmy numer wersji bödzie
mieè kiedykolwiek postaè dwucyfrowñ?

Czy numer wersji oparty jest na dacie ostatniej modyfikacji interfejsu
API?

Kup książkę

Poleć książkę

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:

Co siö stanie ze starszymi wersjami?

Co siö stanie z aplikacjami zaprojektowanymi na bazie starszych wersji?

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?

Czy dysponujesz planem minimalizowania liczby sytuacji, w których

prosisz projektantów o aktualizowanie lub zmienianie wersji?

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

Kup książkę

Poleć książkę

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ñ:

obsäugö wielu interfejsów API (uciñĔliwe);

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);

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.

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

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:

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.

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.

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.

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

Kup książkę

Poleć książkę

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

Kup książkę

Poleć książkę

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

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

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.

Kup książkę

Poleć książkę

193

Skorowidz

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

B2D, Business-to-Developer, 69
blokowanie skoków, 152

bramy interfejsów API, 155
buforowanie, 107, 155

CDN, Content Delivery Network, 155
cel biznesowy, 66
centrum danych, 106

chmura, 106, 157
CRUD, 92

CSS, Cross-Site Scripting, 128

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

elastyczne udostöpnianie treĈci, 32
elementy äaþcucha wartoĈci, 41, 48

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

Kup książkę

Poleć książkę

194

Skorowidz

format

Google Transit, 33
JSON, 99, 124

XML, 99, 124

globalne dostarczanie interfejsu API,

108

GPS, 109

hasäa, 116
HATEOAS, 93, 95

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

JSON, JavaScript Object Notation, 99

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,

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

liczba funkcji, 90
lojalnoĈè, 163

äaþcuch wartoĈci, 37–39
äatwoĈè

testowania, 87
uĔywania, 87
zrozumienia, 88

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

Kup książkę

Poleć książkę

Skorowidz

_ 195

miara sukcesu, 159

modele

biznesowe interfejsów API, 60, 62

konsumpcji, 26

monitorowanie, 144

motywacje projektantów, 174

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

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

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

rekomendacje technologiczne, 83

relacje z partnerami, 43
REST, Representational State

Transfer, 92

rezygnacja z wersji, 104

Kup książkę

Poleć książkę

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

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,

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

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

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

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

Kup książkę

Poleć książkę