നിങ്ങളുടെ ഡെവലപ്പർമാർക്ക് ആദ്യ ദിവസം മുതൽ പിന്തുടരാൻ കഴിയുന്ന വ്യക്തമായ API ഡോക്യുമെന്റേഷൻ ഞാൻ എഴുതും

എന്തുകൊണ്ടാണ് മിക്ക API ഡോക്യുമെന്റുകളും പരാജയപ്പെടുന്നത്

അവ എൻഡ്‌പോയിന്റുകളെക്കുറിച്ച് വിവരിക്കുകയും ആളുകളെ യഥാർത്ഥത്തിൽ തടയുന്ന ഭാഗങ്ങൾ ഒഴിവാക്കുകയും ചെയ്യുന്നു: എങ്ങനെ ആധികാരികമാക്കാം, ഒരു യഥാർത്ഥ അഭ്യർത്ഥന എങ്ങനെയിരിക്കും, പിശകിന്റെ അർത്ഥമെന്താണ്, അതിനെക്കുറിച്ച് എന്തുചെയ്യണം. വായനക്കാരൻ പിന്നീട് ഒരു സപ്പോർട്ട് ടിക്കറ്റ് തുറക്കുന്നു, ഇത് ഡോക്യുമെന്റേഷൻ ഇല്ലാതാക്കാൻ നിലവിലുള്ള ചെലവാണ്.

ഞാൻ എങ്ങനെയാണ് ഇത് എഴുതുന്നത്

ഓർമ്മയിൽ നിന്നല്ല, ഉറവിടത്തിൽ നിന്ന്. ഞാൻ റൂട്ടുകൾ, വാലിഡേഷൻ ലെയർ, എറർ ഹാൻഡ്ലറുകൾ എന്നിവ വായിക്കുകയും യഥാർത്ഥ ക്രെഡൻഷ്യലുകൾ ഉപയോഗിച്ച് API സ്വയം വിളിക്കുകയും ചെയ്യുന്നു. ഡോക്യുമെന്റേഷനിലെ ഓരോ ഉദാഹരണവും ഞാൻ ഉണ്ടാക്കിയ ഒരു അഭ്യർത്ഥനയും എനിക്ക് ലഭിച്ച ഒരു പ്രതികരണവുമാണ് — കെട്ടിച്ചമച്ച പേലോഡുകളോ, എൻഡ്‌പോയിന്റ് ഒരിക്കലും തിരികെ നൽകാത്ത സ്റ്റാറ്റസ് കോഡുകളോ ഇല്ല.

ഡോക്യുമെന്റേഷനിൽ എന്തൊക്കെ അടങ്ങിയിരിക്കുന്നു

• ആധികാരികത: ഒരു ടോക്കൺ നേടുക, അത് പുതുക്കുക, സെഷന്റെ മധ്യത്തിൽ അത് കാലഹരണപ്പെടുമ്പോൾ എന്ത് സംഭവിക്കുന്നു.
• പാരാമീറ്ററുകൾ, ഒരു പൂർണ്ണ ഉദാഹരണ അഭ്യർത്ഥന, യഥാർത്ഥ പ്രതികരണ രൂപം എന്നിവയുള്ള ഓരോ എൻഡ്‌പോയിന്റും.
• ഓരോ പിശക് കോഡിനെയും ഒരു കാരണത്തിലേക്കും പരിഹാരത്തിലേക്കും മാപ്പ് ചെയ്യുന്ന ഒരു പിശക് റഫറൻസ്, സന്ദേശം ആവർത്തിക്കുന്നതിനുപകരം.
• ഒരു പുതിയ ഡെവലപ്പറെ പൂജ്യത്തിൽ നിന്ന് പത്ത് മിനിറ്റിനുള്ളിൽ വിജയകരമായ ഒരു കോളിലേക്ക് എത്തിക്കുന്ന ഒരു ഗെറ്റിംഗ്-സ്റ്റാർട്ടഡ് പാത.
• റേറ്റ് ലിമിറ്റുകൾ, പേജിനേഷൻ, വെബ്ഹുക്കുകൾ, ഐഡംപൊട്ടൻസി എന്നിവ അവ യഥാർത്ഥത്തിൽ ബാധകമാകുന്നിടത്ത് വിശദീകരിക്കുന്നു.

ഫോർമാറ്റ്

നിങ്ങളുടെ റിപ്പോസിറ്ററിയിലെ മാർക്ക്ഡൗൺ, OpenAPI-യ്‌ക്കോ ഡോക്സ് സൈറ്റിനോ വേണ്ടി ഘടനാപരമായത് — നിങ്ങൾ യഥാർത്ഥത്തിൽ പരിപാലിക്കുന്ന ഏതാണോ അത്. നിങ്ങളുടെ ഉപയോക്താക്കൾ ചോദിക്കുന്ന ഭാഷകളിലെ കോഡ് സാമ്പിളുകൾ, അവ പ്രവർത്തിപ്പിച്ച് പരിശോധിച്ചത്. നിങ്ങൾക്ക് വേണമെങ്കിൽ പോസ്റ്റ്മാൻ അല്ലെങ്കിൽ സമാനമായ ശേഖരം ഉൾപ്പെടുത്തിയിട്ടുണ്ട്.

എനിക്ക് വേണ്ടത്

റിപ്പോസിറ്ററി ആക്സസ് അല്ലെങ്കിൽ OpenAPI ഫയൽ, ഒരു ടെസ്റ്റ് എൻവയോൺമെന്റിനായുള്ള ഒരു പ്രവർത്തിക്കുന്ന ക്രെഡൻഷ്യൽ, നിങ്ങളുടെ സപ്പോർട്ട് ടീം മറുപടി നൽകി മടുത്ത ഏതെങ്കിലും ചോദ്യങ്ങൾ. ആ ചോദ്യങ്ങളാണ് രൂപരേഖ.

ഉൾപ്പെടുത്തിയിട്ടില്ല

മാർക്കറ്റിംഗ് കോപ്പി. ഇത് സോഫ്റ്റ്‌വെയർ എന്താണ് ചെയ്യുന്നതെന്ന് കൃത്യമായി രേഖപ്പെടുത്തുന്നു; ലാൻഡിംഗ് പേജ് ഒരു വ്യത്യസ്ത കരകൗശലമാണ്.

തിരിച്ചുവരവും ആശയവിനിമയവും

ആദ്യത്തെ പൂർണ്ണമായ ഡ്രാഫ്റ്റ് സാധാരണയായി ഒരാഴ്ചയ്ക്കുള്ളിൽ ലഭിക്കും, നിങ്ങളുടെ സ്വന്തം സപ്പോർട്ട് ടീം മറുപടി നൽകിക്കൊണ്ടിരിക്കുന്ന ചോദ്യങ്ങൾക്കെതിരെ നിങ്ങൾ അത് അവലോകനം ചെയ്യുന്നു. എഡ്ജ് കേസുകൾ അറിയുന്ന എഞ്ചിനീയർ നേരത്തെ തിരുത്തുന്നതാണ് എനിക്ക് ഇഷ്ടം, മിനുക്കിയതും തെറ്റായതുമായ ഒന്ന് നൽകുന്നതിനേക്കാൾ. അന്തിമ ഡോക്യുമെന്റിലെ ഓരോ ഉദാഹരണവും നിങ്ങളുടെ API-യ്‌ക്കെതിരെ പ്രവർത്തിപ്പിച്ചിട്ടുണ്ട്, അതിനാൽ അതിൽ അഭിലഷണീയമായ ഒന്നും ഇല്ല.