Susulat Ako ng Malinaw na Dokumentasyon ng API na Maaaring Sundin ng Iyong mga Developer Mula sa Unang Araw

Bakit nabigo ang karamihan sa mga dokumento ng API

Inilalarawan nila ang mga endpoint at nilalaktawan ang mga bahagi na talagang pumipigil sa mga tao: kung paano mag-authenticate, kung ano ang hitsura ng isang makatotohanang kahilingan, kung ano ang ibig sabihin ng error, at kung ano ang gagawin tungkol dito. Pagkatapos ay magbubukas ang mambabasa ng isang support ticket, na siyang gastos na inalis ng dokumentasyon.

Paano ko ito isinusulat

Mula sa pinagmulan, hindi mula sa memorya. Binabasa ko ang mga ruta, ang validation layer at ang mga error handler, pagkatapos ay tinatawagan ko ang API mismo gamit ang tunay na mga kredensyal. Ang bawat halimbawa sa dokumentasyon ay isang kahilingan na ginawa ko at isang tugon na natanggap ko — walang imbento na mga payload, walang mga status code na hindi kailanman ibinabalik ng endpoint.

Ano ang nilalaman ng dokumentasyon

• Authentication: pagkuha ng token, pag-refresh nito, at kung ano ang mangyayari kapag nag-expire ito sa kalagitnaan ng session.
• Bawat endpoint na may mga parameter, isang kumpletong halimbawa ng kahilingan, at ang tunay na hugis ng tugon.
• Isang sanggunian ng error na nagmamapa sa bawat error code sa isang sanhi at isang solusyon, sa halip na ulitin lamang ang mensahe.
• Isang landas sa pagsisimula na nagdadala ng isang bagong developer mula sa zero hanggang sa isang matagumpay na tawag sa loob ng wala pang sampung minuto.
• Ipinaliwanag ang mga limitasyon sa rate, pagination, webhooks at idempotency kung saan sila talagang nalalapat.

Format

Markdown sa iyong repository, naka-structure para sa OpenAPI o isang docs site — alinman ang talagang pananatilihin mo. Mga sample ng code sa mga wika na tinatanong ng iyong mga user, na-verify sa pamamagitan ng pagpapatakbo sa kanila. Kasama ang Postman o katulad na koleksyon kung gusto mo.

Ano ang kailangan ko

Access sa repository o ang OpenAPI file, isang gumaganang kredensyal para sa isang test environment, at anumang mga tanong na pagod nang sagutin ng iyong support team. Ang mga tanong na iyon ang balangkas.

Hindi kasama

Marketing copy. Idinodokumento nito kung ano ang ginagawa ng software, nang tumpak; ang landing page ay ibang sining.

Turnaround at komunikasyon

Ang isang unang kumpletong draft ay karaniwang dumarating sa loob ng isang linggo, at sinusuri mo ito laban sa mga tanong na patuloy na sinasagot ng iyong sariling support team. Mas gugustuhin kong itama nang maaga ng engineer na nakakaalam ng mga edge case kaysa maghatid ng isang pinakintab at mali. Ang bawat halimbawa sa huling dokumento ay naisakatuparan laban sa iyong API, kaya walang anuman dito ang aspirational.