உங்கள் டெவலப்பர்கள் முதல் நாளிலிருந்தே பின்பற்றக்கூடிய தெளிவான API ஆவணங்களை நான் எழுதுவேன்

பெரும்பாலான API ஆவணங்கள் ஏன் தோல்வியடைகின்றன

அவை இறுதிப்புள்ளிகளை விவரிக்கின்றன மற்றும் மக்களை உண்மையில் தடுக்கும் பகுதிகளைத் தவிர்க்கின்றன: எவ்வாறு அங்கீகரிப்பது, ஒரு யதார்த்தமான கோரிக்கை எப்படி இருக்கும், பிழை என்ன அர்த்தம், அதை எப்படி சரிசெய்வது. பின்னர் வாசகர் ஒரு ஆதரவு டிக்கெட்டைத் திறக்கிறார், இது ஆவணங்கள் நீக்கப்பட வேண்டிய செலவு.

நான் அதை எப்படி எழுதுகிறேன்

மூலத்திலிருந்து, நினைவிலிருந்து அல்ல. நான் வழிகள், சரிபார்ப்பு அடுக்கு மற்றும் பிழை கையாளுபவர்களைப் படிக்கிறேன், பின்னர் உண்மையான சான்றுகளுடன் API ஐ நானே அழைக்கிறேன். ஆவணங்களில் உள்ள ஒவ்வொரு எடுத்துக்காட்டும் நான் செய்த ஒரு கோரிக்கை மற்றும் நான் பெற்ற ஒரு பதில் — புனையப்பட்ட பேலோடுகள் இல்லை, இறுதிப்புள்ளி ஒருபோதும் திரும்பப் பெறாத நிலை குறியீடுகள் இல்லை.

ஆவணத்தில் என்ன உள்ளது

• அங்கீகாரம்: ஒரு டோக்கனைப் பெறுதல், அதை புதுப்பித்தல் மற்றும் அமர்வின் நடுவில் அது காலாவதியானால் என்ன நடக்கும்.
• அளவுகள், ஒரு முழுமையான எடுத்துக்காட்டு கோரிக்கை மற்றும் உண்மையான பதில் வடிவம் கொண்ட ஒவ்வொரு இறுதிப்புள்ளியும்.
• ஒவ்வொரு பிழைக் குறியீட்டையும் ஒரு காரணம் மற்றும் ஒரு திருத்தத்துடன் இணைக்கும் ஒரு பிழை குறிப்பு, செய்தியை மீண்டும் மீண்டும் கூறுவதற்குப் பதிலாக.
• ஒரு புதிய டெவலப்பரை பூஜ்ஜியத்திலிருந்து பத்து நிமிடங்களுக்குள் ஒரு வெற்றிகரமான அழைப்பிற்கு அழைத்துச் செல்லும் ஒரு தொடக்கப் பாதை.
• விகித வரம்புகள், பக்கவாட்டு, வெப்ஹூக்குகள் மற்றும் ஐடெம்போடென்சி ஆகியவை அவை உண்மையில் பொருந்தும் இடங்களில் விளக்கப்பட்டுள்ளன.

வடிவம்

உங்கள் களஞ்சியத்தில் Markdown, OpenAPI அல்லது ஒரு ஆவண தளத்திற்காக கட்டமைக்கப்பட்டது — நீங்கள் உண்மையில் பராமரிக்கும் எதுவாக இருந்தாலும். உங்கள் பயனர்கள் கேட்கும் மொழிகளில் குறியீடு மாதிரிகள், அவற்றை இயக்குவதன் மூலம் சரிபார்க்கப்பட்டது. நீங்கள் விரும்பினால் Postman அல்லது ஒத்த தொகுப்பு சேர்க்கப்பட்டுள்ளது.

எனக்கு என்ன தேவை

களஞ்சிய அணுகல் அல்லது OpenAPI கோப்பு, ஒரு சோதனை சூழலுக்கான ஒரு வேலை செய்யும் சான்று மற்றும் உங்கள் ஆதரவு குழு பதிலளித்து சோர்வடைந்த எந்த கேள்விகளும். அந்தக் கேள்விகள் தான் அவுட்லைன்.

சேர்க்கப்படவில்லை

சந்தைப்படுத்தல் நகல். இது மென்பொருள் என்ன செய்கிறது என்பதை துல்லியமாக ஆவணப்படுத்துகிறது; இறங்கும் பக்கம் ஒரு வேறுபட்ட கலை.

திருப்புமுனை மற்றும் தொடர்பு

முதல் முழுமையான வரைவு பொதுவாக ஒரு வாரத்திற்குள் வரும், மேலும் உங்கள் சொந்த ஆதரவு குழு தொடர்ந்து பதிலளிக்கும் கேள்விகளுக்கு எதிராக அதை நீங்கள் மதிப்பாய்வு செய்கிறீர்கள். மெருகூட்டப்பட்ட மற்றும் தவறான ஒன்றை வழங்குவதை விட, விளிம்பு நிகழ்வுகளை அறிந்த பொறியாளரால் ஆரம்பத்திலேயே திருத்தப்படுவதை நான் விரும்புகிறேன். இறுதி ஆவணத்தில் உள்ள ஒவ்வொரு எடுத்துக்காட்டும் உங்கள் API க்கு எதிராக செயல்படுத்தப்பட்டுள்ளது, எனவே அதில் எதுவும் லட்சியமாக இல்லை.