+1
a legtobb fejleszto a peldakbol latja at leginkabb a mukodest.
legyen teljes api dokumentacio, de amint mar tobben is irjak, az onmagaban keves.
legyen egy high level attekintes a rendszerrol, majd csoportokra bontva az egyes API reszek bemutatasa, szinten szovegesen hogy mi mire jo, milyen fogalmak alatt mit kell erteni (pl. egy vasarlasi/fizetesi rendszernel legyen definialva, hogy mit ertunk vasarlo, termek, kosar, tranzakcio alatt, etc.) majd az egyes muveleteket mutassa be 1-1 rovid peldaval is.
amit meg sok helyrol hianyolok, az annak a bemutatasa, hogy hogyan kell a kulonbozo api hivasokat egyutt hasznalni.
tehat pl. api doksibol kiderul, hogy a rendelesfeladas var egy customer meg egy kosar parametert, de ott nem mutatja be, hogy ezeket hogy kellett letrehozni, inicializalni ahhoz, hogy itt ne kapjunk titokzatos hibauzeneteket.
apropo, hibauzenetek, az API hivasoknal visszaadott hibauzenetek utaljanak a tenyleges problemara, lehetoleg minnel pontosabban behatarolhatoan, a dokumentacio szintugy tartalmazza, a lehetseges hibakodok listaja magyarazattal.
es ha az API tervezes fazisaban vagyunk, akkor erdemes a "principle of least astonishment"-et betartani, ha valami felreertheto/ketertelmu, akkor javitsuk ki, vagy ha nem lehet, akkor legalabb hivjuk fel ra a figyelmet a dokumentacioban, meg esetleg a hibauzenetben is.
es amit meg szeretek, ha van kesz pelda integracio tobb nyelven (de legalabb javaban).
ps: kicsit mar a 3rd party/web service jellegu APIkat is szem elott tartottam a comment irasakor, bar most utolag atfutva talan nincs semmi olyan a hozzaszolasomban, ami egy offline library sdk-ban ertelmetlen lenni.
Tyrael