Developing in the clouds

Czasami zdarza się sytuacja, że część zespołu projektuje API, a deweloper musi odwoływać się do niego w swojej aplikacji. W momencie, gdy dwa zespoły pracują równolegle może pojawić się problem – Twoje zadanie zostaje zablokowane do momentu ukończenia jakiejś części tego API. Można sobie z tym poradzić na kilka sposobów. W sieci znajdziemy mnóstwo narzędzi pozwalających na zmockowanie danych. Ostatnio moją uwagę przykuł serwis apiary.io. Oferuje on możliwość zaprojektowania własnych endpointów i co najważniejsze – pozwala komunikować się z nimi przez zapytania HTTP.

Ile to kosztuje?

Apiary oferuje trzy plany: Free, Standard oraz Pro. Jak się można domyśleć, ten pierwszy jest za darmo. Są jednak pewne ograniczenia. Nasze darmowe API może projektować maksymalnie pięć osób jednocześnie. Z najważniejszych rzeczy darmowy plan oferuje podstawowe funkcje synchronizacji z GitHub’em, dostęp do edytora Blueprint’a, mock serwer, interaktywną dokumentację API, inspektor do podglądania request’ów oraz możliwość przygotowania testów automatycznych. Jak na darmową opcję uważam, że to całkiem sporo funkcjonalności. Przeglądając pełne porównanie planów (które znajdziecie tutaj)  ciekawą funkcjonalnością, której może brakować jest podział na mniejsze Blueprint’y. W dużych projektach istnieje ryzyko, że utworzymy dokument na setki linijek kodu i konfiguracji, którego edycja może być w przyszłości uciążliwa (tutaj testy automatyczne na pewno się przydadzą). Plan Standard to kilka dodatkowych opcji ułatwiających pracę w zespole maksymalnie do 20 osób (cena zaczyna się od 99$ dla dziesięciu osób miesięcznie), natomiast plan Pro to pełny zestaw funkcjonalności, a wielkość zespołu ustalana jest indywidualnie poprzez kontakt z zespołem Apiary.

Blueprint – edytor i dokumentacja

Do serwisu można zalogować się kontem z GitHub’a lub Twitter’a. Jeśli nie chcemy powiązać swojego konta z Apiary, możemy utworzyć osobne. Rejestracja nic nie kosztuje. Po zalogowaniu się do serwisu możemy utworzyć nasze pierwsze API. Zostaniemy zapytani o jego nazwę, a następnie przekierowani do edytora. Po lewej stronie zobaczymy nasz Blueprint z domyślnym przykładem API z ankietami, a po prawej interaktywną dokumentacją z możliwością jej przeglądania.

Format, metadane i dokumentacja projektu

Każdy endpoint można dokumentować w bardzo prosty sposób. Odpowiednie komentarze poprzedzamy znakiem # (pojedynczym, podwójnym lub potrójnym). Apiary ułatwia nam również zadanie z pisaniem kodu wykonującego request, automatycznie generując fragment kodu w wybranym języku. Przyjrzyjmy się budowie Blueprint’a.

Słowo kluczowe FORMAT jest wymagane dla każdego projektu, znajduje się zawsze na początku dokumentu i oznacza, że tworzony przez nas dokument to właśnie Blueprint. Słowo kluczowe HOST to produkcyjny url naszego API i jest ono opcjonalne. Po pojedynczym znaku # znajduje się nazwa naszego API, a w kolejnej linii jego krótki opis. Po kliknięciu “Save” zostanie wygenerowana dokumentacja na podstawie zbudowanego przez nas do tej pory Blueprint’a. Warto też zwrócić uwagę, że dokument jest walidowany i w przypadku złej konfiguracji, Apiary poinformuje nas o błędzie.

Resource i akcje

Nazwę naszego resource’a definiujemy po podwójnym znaku krzyżyka (##), a zaraz po nim w kwadratowych nawiasach URI pod którym dostępny będzie nasz resource. Ponownie w ten sam sposób możemy dodać opis w nowej linii. Następnie po potrójnym znaku krzyżyka (###) definiujemy akcję oraz typ metody HTTP, a w nowej linii dodajemy ponownie opis mówiący co dana akcja będzie robić. Teraz przechodzimy do “ciała” całej akcji. Po znaku “+” definiujemy jak wygląda odpowiedź dla naszego requesta, jaki będzie HTTP status code i jaki jest content type. W kolejnych liniach wpisujemy dane w formacie JSON, które będą zwracane. W podobny sposób możemy zdefiniować jak ma wyglądać request, możemy też ustawić nagłówki HTTP.

Hello world!

Czas stworzyć coś własnego. Zacznijmy od tradycyjnego”Hello world!”. Utworzę sobie projekt o nazwie “blog-helloworld”. Nadam nazwę mojemu API i stworzę prosty resource, który zwróci mi JSON z zapisem “Hello world!”.

Po zapisaniu Blueprint’a dostajemy link do mock serwera (do podejrzenia w interaktywnej dokumentacji): http://private-8a601-bloghelloworld.apiary-mock.com/hello.

Podsumowanie

Apiary jest ciekawym narzędziem pozwalającym w prosty i szybki sposób zaprojektować nasze API. Dzięki temu czekając na jakiś endpoint dla naszej aplikacji możemy sami sobie przygotować odpowiednie akcje i z nich korzystać, a nasz development nie stanie w miejscu. Jest to bardzo prosty sposób na wymianę wiedzy w zespole i przedstawienie wymagań co do oczekiwanych odpowiedzi serwera, a interaktywna dokumentacja pozwala w łatwy sposób pokazać drugiej części zespołu jak powinien działać nasz endpoint. Jedynym minusem darmowej wersji jest ciągle narastający dokument projektu, gdzie przy bardziej skomplikowanych akcjach przewijanie naszego Blueprint’a może być uciążliwe. Mimo to chętnie wykorzystuję to narzędzie do mniejszych celów i zachęcam wszystkich do zapoznania się z nim. 🙂