การจัดโครงสร้างเอกสารออนไลน์สำหรับ REST API

ฉันกำลังสร้าง Rest API ตัวแรกซึ่งจัดลำดับข้อมูลเป็นรูปแบบ JSON และ XML ฉันต้องการให้หน้าดัชนีแก่ไคลเอ็นต์ API ซึ่งพวกเขาจะสามารถเลือกจุดสิ้นสุดที่ใช้งานได้

ข้อมูลใดบ้างที่ฉันต้องรวมไว้เพื่อให้ API ของฉันมีประโยชน์สูงสุดและฉันควรจัดระเบียบอย่างไร

นั่นเป็นคำถามที่ซับซ้อนมากสำหรับคำตอบง่ายๆ

คุณอาจต้องการที่จะดูที่กรอบ API ที่มีอยู่เช่นวางท่าสเปกสินค้า ( OpenAPI ) และบริการเช่นapiary.ioและapiblueprint.org

นอกจากนี้นี่คือตัวอย่างของ REST API เดียวกันที่อธิบายจัดระเบียบและแม้กระทั่งสไตล์ในสามวิธีที่แตกต่างกัน อาจเป็นการเริ่มต้นที่ดีสำหรับคุณในการเรียนรู้จากวิธีการทั่วไปที่มีอยู่

• https://api.coinsecure.in/v1
• https://api.coinsecure.in/v1/originalUI
• https://api.coinsecure.in/v1/slateUI#!/Blockchain_Tools/v1_bitcoin_search_txid

ในระดับบนสุดฉันคิดว่าเอกสาร REST API ที่มีคุณภาพต้องการอย่างน้อยดังต่อไปนี้:

• รายการปลายทาง API ทั้งหมดของคุณ (URL พื้นฐาน / สัมพัทธ์)
• ประเภทเมธอด HTTP GET / POST / ... ที่สอดคล้องกันสำหรับแต่ละจุดสิ้นสุด
• คำขอ / ตอบกลับประเภท MIME (วิธีเข้ารหัสพารามิเตอร์และแยกวิเคราะห์การตอบกลับ)
• คำขอ / การตอบกลับตัวอย่างรวมถึงส่วนหัว HTTP
• ชนิดและรูปแบบที่ระบุสำหรับพารามิเตอร์ทั้งหมดรวมถึงที่อยู่ใน URL เนื้อหาและส่วนหัว
• คำอธิบายข้อความสั้น ๆ และบันทึกย่อที่สำคัญ
• ข้อมูลโค้ดสั้น ๆ ที่แสดงการใช้ปลายทางในภาษาโปรแกรมเว็บยอดนิยม

นอกจากนี้ยังมีเฟรมเวิร์กเอกสารที่ใช้ JSON / XML จำนวนมากซึ่งสามารถแยกวิเคราะห์นิยาม API หรือสคีมาของคุณและสร้างชุดเอกสารที่สะดวกสำหรับคุณ แต่ทางเลือกสำหรับระบบการสร้างเอกสารนั้นขึ้นอยู่กับโครงการภาษาสภาพแวดล้อมการพัฒนาและสิ่งอื่น ๆ อีกมากมาย