APIX - programista też klient

Miałam ostatnio okazję być na wrocławskim JUGu, na którym Paweł Zajączkowski opowiadał o projektowaniu Web API. Poza tym, że zostałam wzięta za rekruterkę (wow wow, community takie otwarte), to otworzyły mi się oczy na kilka nowych tematów. Na codzień pracuję z Web API i staram się projektować je w sposób przyjazny jego użytkownikom (najczęściej developerom na froncie). Okazuje się, że to nazywa się APIX - API Experience. To taki piękny punkt, w którym biznesowy świat UX wkracza w czeluści kodu backendowego. Bo jako programiści nawzajem też jesteśmy swoimi klientami i też powinniśmy dbać o komunikację między naszymi serwisami, albo komponentami.

Doświadczony developer wie, że częściej czyta się kod, niż się go pisze. No może greenfieldowe projekty mają na początku odwrotne statystyki, ale z biegiem czasu zrównują się z innymi. Cały kod, który jest w projekcie, api, komendy devopsowe, wszystko jest danym nam dziedzictwem, zwanym legacy /ˈlɛɡəsi/. Żeby efektywnie dbać o to dziedzictwo, powinno być ono w 100% nasze, albo dobrze napisane. I tu zaczynają się schody, bo to dla każdego znaczy coś innego. Jedni lubią długie, opisowe nazwy, wprowadzanie zmiennych, rozbijanie kodu na wiele metod. Inni preferują haskellowskie jednolinijkowce, bez zbędnego rozdrabniania. Tutaj nie ma złych i dobrych rozwiązań, to każdy zespół musi sobie wypracować sam. 

Jak radzimy sobie z projektowaniem API w naszym projekcie? 

• używamy jak najkrótszych, ale jednoznacznych nazw
• zmieniamy nazwy pól w zależności od endpointów, dodajemy przedrostki tam, gdzie wartości są "obce", n.p. to co w produkcie nazywa się po prosu name, w historii zamówień już jest productName (tak, wszędzie camelCase'y)
• zmniejszamy ilość danych do niezbędnego minimum, to oznacza maintenace payloadu, stronicowanie i filtrowanie
• używamy wielu różnych kodów, facebookowe okejki nie zdałyby u nas egzaminu
• walidujemy przychodzące dane, nawet jeśli frontend też je waliduje

Naszą największą bolączką w tej chwili jest dokumentacja API, bo Swagger dla Akki Http potwornie zaśmieca kod. Może masz jakiś sprawdzony sposób, którym możesz się podzielić?