O tym jak nieścisłości w dokumentacji przyprawiają programistę o siwy włos

Siedzę sobie i integruję można by rzec. Integruję swoją aplikację z API serwisu furgonetka.pl. Ogólnie rozwiązanie zajebiste, żądania ładnie idą po http, odpowiedzi dostaję w pięknych jsonach. Wszystko idealnie. Tylko dlaczego dokumentacja do tego API jest tak ogólnikowa? Tak bardzo zrobiona po łebkach? Dlaczego za każdym razem trzeba się wszystkiego domyślać?  

Na ruszt weźmy metodę packageAdd zamarynowaną ponad 60 parametrami. Wiadomo, najpierw trzeba przeczytać co jest wymagane, a co nie, żeby później się nie męczyć. No to czytam – „Typ paczki (dopuszczalne wartości: ‚package’ – paczka, ‚dox’ – koperta, ‚pallette’ – paleta)„.

Wszystko pięknie, chociaż na pierwszy rzut oka paleta w paczkomacie odpada. Zaczynam pisać testy, wskazuję kuriera Inpost, jako typ paczkę – działa. Jestem zadowolony. Później wskazuje Inpost, typ koperta – nie działa. WTF? Przecież odbieram z paczkomatów koperty, o co chodzi? Pierwsze co myślę coś jest źle z wymiarami. Podaje większe niż dopuszczalne – dostaję odpowiedź, że za duże. Podaje wymiary, które mieszczą się w granicach – pokazuje mi, że złe są.

WTFx2 

I dopiero po dłuższej chwili zadumy, wybieram kopertę i nie podaję wymiarów. Nareszcie błąd na który czekałem. „Podana usługa nie jest zgodna z ofertą wybranego kuriera” (czy coś w ten deseń). Mimo, że zaczynałem już się domyślać o co chodzi to miałem WTFx3. Do tego ciągle przede mną leżała koperta z etykietą Inpost. Wiadomo zatem, że kopertę do paczkomatu można wsadzić i nic nie wybuchnie.

Co się okazało? W API furgonetki jedynym możliwym typem przesyłki dla paczkomatów jest paczka (w sumie jak sama nazwa wskazuje :-D). Nie koperta, nie paleta. Paczka. Ale po co o tym wspomnieć w dokumentacji. Wystarczyło do powyższego dopisać „Dla usługi inpost tylko ‚package'”. Dokładnie 5 słów. 3 sekundy pisania. Ja na tym straciłem ok. 15 minut. Czyli 300 razy więcej czasu niż dopisanie tego zdania zajęłoby osobie która tę dokumentację pisała. Pewnie takich kwiatków jest więcej, ale co zrobisz jak nic nie zrobisz.

Druga sprawa to zagmatwanie z poplątaniem w wymiarach paczek. Wymagane parametry: width, hieight i depth. Pomijając fakt, że wysokość i głębokość dla paczki to to samo. A wystarczyłoby zmienić height na length i po problemie. Gdzie length to najdłuższy bok paczki (bo teraz jest nim width). I nad rozgryzaniem tych wymiarów spędziłem następną godzinkę jak nie lepiej.

Oczywiście przesłałem do furgonetki swoje uwagi i na szczęście zobowiązują się do poprawek. Co mnie bardzo cieszy, bo kolejni programiści będą mieli jaśniejszą sytuację.

Jakie płyną z tego wnioski? Testy jednostkowe mnie ubezpieczyły, bo inaczej siedziałbym i klikał jak debil i stracił na to jeszcze więcej czasu. Drugi jest taki, że nazewnictwo ma znaczenie. A trzeci wniosek, właściwie prośba jest taka – drodzy programiści, jeżeli stworzycie jakieś API to stwórzcie też dokładną dokumentację dla niego. To, że ktoś chce się zintegrować z Waszym systemem jest nie tylko powodem do dumy, ale też zapewne korzyścią finansową. Tworząc precyzyjną dokumentację pomagacie swoim kolegom po fachu, a jak wiadomo trzeba sobie pomagać.

Kończąc już mój wywód. Z samego rozwiązania i sposobu integracji z furgonetką jestem bardzo zadowolony i będę polecał dalej. Jest wygodne i przyjemnie się z nim pracuje. Dokumentacja jednak zdecydowanie do poprawy. Proszę 🙂

Mieliście podobne problemy z dokumentacjami?

Czekam na komentarze i do zobaczenia następnym razem!

Reklamy

3 comments

  1. Pingback: dotnetomaniak.pl
  2. Moim zdaniem dokumentacja API (w tym konkretnym przypadku) dobrze że nie opisuje reguł biznesowych, jakimi dla mnie są obsługiwane rodzaje przesyłek, firm transportowych itd.
    Jest to dla mnie element ‚konfigurowalny’, który może (z dużym prawdopodobieństwem) ulec zmianie.
    Innymi słowy, dla dokumentacji samego API (serwisy, metody) zastosowałbym zasadę open/close – opisujemy to co jest niezbędne, sam kontrakt nic więcej.
    Reszta, jak dopuszczalna konfiguracja wartości, powinna być załącznikiem do dokumentacji. Taki załącznik można modyfikować,publikować … niezależnie.
    Moim zdaniem omawiane API można było lepiej zamodelować np. wprowadzając odpowiednie obiekty dla poszczególnych usługodawców oraz grupę obiektów wymaganych zawsze, lub inne ‚grupowanie’ obiektów (np. część ogólna – wymagana zawsze oraz elementu konfigurowalne – na które zawsze nakładają się jakieś reguły biznesowe).

    Polubienie

    1. W 100% się zgadzam. W każdym razie ani w dokumentacji ani w żadnym załączniku (bo takowych) nie było, nie ma żadnej wzmianki o różnych przypadkach. Nic to, doszedłem w końcu do efektu jakiego oczekiwałem (chociaż po ciężkiej walce niekiedy) i mam nadzieję, że coś z tym zrobią, żeby kolejni śmiałkowie mieli przyjemniejszą pracę 🙂

      Polubienie

Skomentuj

Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:

Logo WordPress.com

Komentujesz korzystając z konta WordPress.com. Wyloguj / Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj / Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj / Zmień )

Zdjęcie na Google+

Komentujesz korzystając z konta Google+. Wyloguj / Zmień )

Connecting to %s