Projektowanie i tworzenie API

Niemal każda duża aplikacja ma w swoich zasobach dostęp przez API, czyli interfejs pozwalający na interakcję z aplikacją bez konieczności wyświetlania jej części przeglądarkowej. Taki interfejs ma najczęściej zastosowanie przy tworzeniu narzędzi do których dostęp mają mieć aplikacje poza systemowe jak na przykład widgety, dodatki i pluginy. Ale jak stworzyć dobre API?

Konsekwentność

API stosuje się zazwyczaj przy tworzenia dodatkowych punktów dostępowych do zasobów aplikacji, dlatego podczas projektowania interfejsu należy pamiętać aby metody zgadzały się w obu przypadkach inaczej ograniczymy funkcjonalność a tym samym przydatność API.

Ograniczenie metod po stronie API nie jest jednak zawsze złe. Zdarzają się zastosowania w których interfejs ma służyć jedynie jako dostęp podglądowy nie zezwalający na tworzenie lub modyfikację danych.

Kolejnym aspektem konsekwentności jest zachowanie struktury zwrotki. Chodzi tutaj o zwracanie takich samych danych w obrębie zasobu. Dla przykładu, gdy nasza zwrotka użytkownika zawiera atrybuty takie jak 'name', 'email', 'avatar' należy zawsze je zwracać w ten sam sposób nie zmieniając tych nazw na 'nick', 'address', 'image'. Takie zmiany powodują bałagan w dokumentacji i znacznie utrudniają tworzenie aplikacji, które mają korzystać z API.

Zabezpieczenia

Zabezpieczenie wszelkiej maści dostępów do danych w bazie danych powinno zawsze być priorytetem przy tworzeniu interfejsu.

API można zabezpieczyć na kilka sposobów. Najpopularniejszym z nich jest zabezpieczenie przy pomocy tokena uwierzytelniającego. Token taki jest generowany przez system API i przypisywany do konkretnego clienta - czyli odbiorcy danych z interfejsu.

Aby taki token otrzymać client musi przesłać na odpowiedni adres swój ID i sekret, który otrzymał przy rejestracji profilu. Na tej podstawie system generuje i przypisuje token dostępowy, który może zostać wykorzystany do autoryzowania zapytań kierowanych do interfejsu.

Pomijając zabezpieczenia dostępowe do danych należy zawsze pamiętać o zabezpieczeniu samego serwera przed przeciążeniem zbyt dużą ilością zapytań lub innymi atakami takimi jak Man-in-the-Middle, które pozwalają na "podsłuch" komunikacji z interfejsem.

Komunikacja

W przypadku aplikacji webowych komunikacja z API odbywa się po protokole HTTP/HTTPS przez przygotowane adresy url. Wysłane żądanie jest przetwarzane i zwracany jest rezultat najczęściej w postaci JSON z danymi lub informacjami o statusie żądania.

W przypadku API korzysta się z metod HTTP aby zdefiniować działania danej akcji API i na przykład akcja z metodą DELETE będzie odpowiadać za usunięcie danego elementu ze zbioru zasobów a PUT tworzyła go. Pozwala nam to ograniczyć ilość url do zasobów do niezbędnego minimum przy wykorzystaniu różnych metod dla tego samego adresu.

Tworząc zapytanie nie zawsze należy przekazywać dane w parametrach url. Bardzo często, np.: w przypadku tworzenia użytkowników, dane lepiej jest przekazać w ukrytych formularzach POST aby zabezpieczyć je przed kradzieżą lub nadpisaniem.

Dane zwrotne

Tworząc API dobrze jest uporządkować dane zwrotne z akcji. Najczęściej spotykaną strukturą jest zwracanie kodu HTTP opisującego status wraz z ewentualnym opisem tekstowym, w innym kluczu dane żądane przez użytkownika i w osobnym ewentualny szerszy opis błędu.

{
	code: 200,
	status: “OK”,
	response:[
		key: “some data”
	]
}

Podsumowanie

Tworząc API należy pamiętać o dobrym zabezpieczeniu środowiska i spójnej strukturze danych zwrotnych. Należy też przemyśleć jakie dane będziemy przyjmować i zwracać aby nie narażać aplikacji na wyciek informacji.

Nie zaleca się też udostępniania API bez ważnych certyfikatów SSL - stwarza to poważne zagrożenie dla bezpieczeństwa całej aplikacji i danych użytkowników.