હું સ્પષ્ટ API દસ્તાવેજીકરણ લખીશ જે તમારા ડેવલપર્સ પ્રથમ દિવસથી અનુસરી શકે છે

શા માટે મોટાભાગના API દસ્તાવેજો નિષ્ફળ જાય છે

તેઓ એન્ડપોઇન્ટ્સનું વર્ણન કરે છે અને તે ભાગોને છોડી દે છે જે ખરેખર લોકોને રોકે છે: કેવી રીતે પ્રમાણિત કરવું, વાસ્તવિક વિનંતી કેવી દેખાય છે, ભૂલનો અર્થ શું છે અને તેના વિશે શું કરવું. પછી રીડર સપોર્ટ ટિકિટ ખોલે છે, જે દસ્તાવેજીકરણ દૂર કરવા માટે અસ્તિત્વમાં છે તે ખર્ચ છે.

હું તેને કેવી રીતે લખું છું

સ્ત્રોતમાંથી, મેમરીમાંથી નહીં. હું રૂટ્સ, વેલિડેશન લેયર અને એરર હેન્ડલર્સ વાંચું છું, પછી વાસ્તવિક ઓળખપત્રો સાથે API ને જાતે કૉલ કરું છું. દસ્તાવેજીકરણમાં દરેક ઉદાહરણ મેં કરેલી વિનંતી અને મને મળેલો પ્રતિભાવ છે — કોઈ શોધાયેલ પેલોડ્સ નથી, કોઈ સ્ટેટસ કોડ્સ નથી જે એન્ડપોઇન્ટ ક્યારેય પરત કરતું નથી.

દસ્તાવેજીકરણમાં શું શામેલ છે

• પ્રમાણીકરણ: ટોકન મેળવવું, તેને તાજું કરવું અને સત્રની મધ્યમાં તેની સમયસીમા સમાપ્ત થાય ત્યારે શું થાય છે.
• પેરામીટર્સ સાથેનો દરેક એન્ડપોઇન્ટ, સંપૂર્ણ ઉદાહરણ વિનંતી અને વાસ્તવિક પ્રતિભાવ આકાર.
• એક ભૂલ સંદર્ભ જે દરેક ભૂલ કોડને કારણ અને સુધારણા સાથે મેપ કરે છે, ફક્ત સંદેશનું પુનરાવર્તન કરવાને બદલે.
• એક શરૂઆતનો માર્ગ જે નવા વિકાસકર્તાને દસ મિનિટથી ઓછા સમયમાં શૂન્યથી સફળ કૉલ સુધી લઈ જાય છે.
• જ્યાં તેઓ ખરેખર લાગુ પડે છે ત્યાં રેટ મર્યાદા, પૃષ્ઠીકરણ, વેબહુક્સ અને આઇડેમ્પોટેન્સી સમજાવવામાં આવી છે.

ફોર્મેટ

તમારા રિપોઝીટરીમાં માર્કડાઉન, ઓપનએપીઆઈ અથવા ડોક્સ સાઇટ માટે સ્ટ્રક્ચર્ડ — જે તમે ખરેખર જાળવી રાખશો. તમારા વપરાશકર્તાઓ પૂછે છે તે ભાષાઓમાં કોડ નમૂનાઓ, તેમને ચલાવીને ચકાસાયેલ. જો તમે ઇચ્છો તો પોસ્ટમેન અથવા સમાન કલેક્શન શામેલ છે.

મને શું જોઈએ છે

રિપોઝીટરી ઍક્સેસ અથવા ઓપનએપીઆઈ ફાઇલ, પરીક્ષણ વાતાવરણ માટે એક કાર્યકારી ઓળખપત્ર અને તમારા સપોર્ટ ટીમ જવાબ આપવાથી કંટાળી ગઈ હોય તેવા કોઈપણ પ્રશ્નો. તે પ્રશ્નો રૂપરેખા છે.

શામેલ નથી

માર્કેટિંગ કોપી. આ સૉફ્ટવેર શું કરે છે તેનું ચોક્કસ દસ્તાવેજીકરણ કરે છે; લેન્ડિંગ પૃષ્ઠ એક અલગ કળા છે.

ટર્નઅરાઉન્ડ અને સંચાર

પ્રથમ સંપૂર્ણ ડ્રાફ્ટ સામાન્ય રીતે એક અઠવાડિયામાં આવે છે, અને તમે તમારા પોતાના સપોર્ટ ટીમ જે પ્રશ્નોના જવાબ આપતી રહે છે તેની સામે તેની સમીક્ષા કરો છો. હું કંઈક પોલિશ્ડ અને ખોટું પહોંચાડવા કરતાં એન્જિનિયર દ્વારા વહેલા સુધારવામાં આવવાનું પસંદ કરીશ જે એજ કેસો જાણે છે. અંતિમ દસ્તાવેજમાં દરેક ઉદાહરણ તમારા API સામે ચલાવવામાં આવ્યું છે, તેથી તેમાં કંઈપણ આકાંક્ષિત નથી.