การเขียนเอกสารประกอบ API

 

การเขียนเอกสารประกอบ API (Application Programing Interface) สำหรับให้ผู้อื่นได้เข้าถึงข้อมูล อย่างมีประสิทธิภาพและปลอดภัย จะต้องเขียนให้ครอบคลุมประเด็นหัวข้อ 5 หัวข้อ ดังนี้

1.URL สำหรับขอ Request 

            ตำแหน่งของ URL endpoint ของ API

2.Method สำหรับการเรียกใช้ API

           จะต้องใช้งานผ่าน HTTP Request ซึ่ง HTTP Request นั้นเป็นการส่งข้อคำขอเพื่อร้องขอข้อมูลกับทางผู้ให้บริการ เช่น การเข้าเว็ปไซต์ต่างๆจะเป็นการส่งคำขอเพื่อรับหน้าเว็ปมาแสดงผล โดย HTTP Request จะต้องระบุ method ที่ใช้งานโดยจากข้อที่แล้ว methed ที่ api กำหนดก็คือ GET

3.Parameter ที่ต้องใช้

        parameter เป็นข้อมูลที่ผู้ให้บริการต้องการใช้ เพื่อการใช้งาน api ตามปกติแล้วจะเป็นการเจาะจงข้อมูลที่ต้องการ เช่น เป็นข้อมูลของวันที่เท่าไหร่ หรือเป็นการใส่ api-key ที่เป็นการกำหนดว่าคนร้องขอเป็นใคร โดยส่วนมากจะต้องสมัครสมาชิกเพื่อรับ api-key ซึ่งจะไม่ซ้ำกับคนอื่น

4.Respond ที่ตอบกลับมา

       เมื่อกดส่งก็จะได้ข้อมูลลักษณะที่เป็นข้อมูลประเภทJSON (รูปแบบข้อมูล String ที่ใช้กันในการส่งข้อมูล) ซึ่งข้อมูลนี้คือผลลัพธ์ที่ทางผู้ให้บริการตอบกลับมาจากข้อมูลทั้งหมดที่ได้ร้องขอ หลังจากนี้คือหน้าที่ของผู้ร้องขอ ว่าจะเอาข้อมูลส่วนไหนไปทำอะไร

5.ข้อกำหนดและข้อตกลง

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

ดูตัวอย่าง

CR: https://www.borntodev.com/c/webdeveloper/%E0%B8%88%E0%B8%B0%E0%B9%83%E0%B8%8A%E0%B9%89-api-%E0%B8%8A%E0%B8%B2%E0%B8%A7%E0%B8%9A%E0%B9%89%E0%B8%B2%E0%B8%99%E0%B8%95%E0%B9%89%E0%B8%AD%E0%B8%87%E0%B8%94%E0%B8%B9%E0%B8%AD%E0%B8%B0%E0%B9%84%E0%B8%A3%E0%B8%9A%E0%B9%89%E0%B8%B2%E0%B8%87-5fa4fe4b04367