Co mają ze sobą wspólnego świetne interfejsy API? [Zamknięte]

Co sprawia, że ​​świetne interfejsy API sprawiają, że są one świetne? Myślę, że przestrzeganie mantry „rób jedną rzecz i rób to dobrze” jest dobrym znakiem, a bycie dobrym mapowaniem do dziedziny problemów jest ważne, ale co mają ze sobą wspólnego świetne interfejsy API?

Trzeba uważać, aby nie dodawać nowego słownictwa tylko ze względu na interfejs API. Moje ulubione interfejsy API wyjaśniają mi słownictwo, które już rozumiem. Wzdłuż tych linii:

Nie dodawaj zbyt wielu abstrakcji do tego, co budujesz. Nie komplikuj.

Już muszę pomyśleć o pół tuzinie warstw abstrakcji. Nie każ mi myśleć o dodatkowych warstwach. Nie dawaj mi zbyt wielu nowych rzeczy do nauczenia, które nie zwiększą wartości mojego końcowego celu. Na przykład unikaj używania własnej specjalnej klasy plików, która działa inaczej niż typ pliku języka, tylko dlatego, że uważasz, że Twoja droga jest lepsza niż ogólnie akceptowana metoda. Trzymaj się ogólnie przyjętego sposobu, przynajmniej na swoich interfejsach, na lepsze lub na gorsze.

Trzymaj się konkretnych pomysłów

Na przykład nie próbuj ukrywać faktu, że część „modelowa” frameworka MVC stanowi interfejs użytkownika bazy danych. Skorzystaj ze znanego słownictwa dotyczącego „baz danych”. Wiem, jakie są klucze obce. Wiem, jakie są wiersze i kolumny. Porozmawiaj ze mną w tych warunkach.

Nie pobieraj niezbędnej wiedzy

Podobne do pracy z konkretnymi pomysłami. Nie ukrywaj, że mamy do czynienia z plikami, bazami danych lub wierszami w bazach danych. Znam te rzeczy. Jeśli mam do czynienia z kontenerem, takim jak Lista, istnieje duża szansa, że ​​muszę znać złożoność algorytmiczną typowych operacji. Możesz to bardzo uprościć, po prostu mówiąc mi, że jest to „lista połączona” lub „tablica”. Ogromny zestaw pomysłów zostanie nagle zastosowany do tego, co robisz i nagle wszystko to będzie miało sens. Nie twórz własnego zestawu pomysłów, których muszę się nauczyć, gdy będę już dysponować bogatym i użytecznym zestawem terminologii, aby zastosować się do problemu.

Zmniejsz liczbę potrzebnych terminów w moim słowniku

Jeśli używam twojego API do otwierania dowolnego pliku obrazu, nie powinienem zbytnio myśleć o pngs vs. gifs vs. jpgs. Zrobisz to dla mnie. To twoja podstawowa kompetencja, nie moja. Mam niejasne zrozumienie, że masz dla mnie trochę magii.

Przydatny interfejs API ma następujące funkcje:

• Zwięzła i dokładna dokumentacja. Jeśli szukam sposobu zaimplementowania zadania, mogę się dowiedzieć, czy interfejs API ma taką możliwość, w ciągu kilku minut. Osiąga się to poprzez zwięzłość tekstu i układ zasobu. Dokumentacja zawiera przykłady, jak z niej korzystać, a także nie przyjmuje żadnych założeń dotyczących czytelnictwa.
• Duża, aktywna społeczność. Jestem zaskoczony, gdy znajduję fora, kanały IRC, listy mailingowe itp. Z aktywnymi uczestnikami chętnymi do pomocy nowym chłopakom. Rozumiem, że zwykle tak jest w przypadku większych projektów, ale nadal warto o nie zabiegać.
• Konsystencja. Kiedy faktycznie używam interfejsu API, nie chcę być w szoku w żaden sposób, gdy wywołuję metodę lub odkrywam, że metoda Xta różni się całkowicie od konwencji ustawionej przez resztę interfejsu API.

Świetne interfejsy API mają świetną dokumentację.

• Zrób jedną rzecz i zrób to świetnie.
• Łatwy w użyciu, trudny do niewłaściwego użycia.
• Łatwy w rozbudowie.
• Dobrze udokumentowane.
• Spójny styl.

To pytanie jest omówione w „Praktycznym projektowaniu API: Wyznania architekta Java Framework” autorstwa Jaroslava Tulacha z zespołu NetBeans.

Najprostszy użyteczny interfejs i dobre konwencje nazewnictwa.