5 กฎทองสำหรับการออกแบบ Web API ที่ยอดเยี่ยม

เคยพบว่าตัวเองสงสัย ว่า เมื่อรวมบริการเว็บผ่าน API? ถ้าไม่ คุณโชคดีกว่าผมมาก

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

ทัศนคติ

ส่วนใหญ่เมื่อคุณสร้างโซลูชัน คุณกำลังออกแบบสำหรับผู้ใช้ปลายทางที่ไม่ใช่โปรแกรมเมอร์ หรือผู้ที่โดยทั่วไปไม่ซับซ้อนในทางเทคนิค คุณกำลังให้อินเทอร์เฟซแบบกราฟิกแก่พวกเขา และหากคุณทำงานได้อย่างถูกต้อง คุณได้รวบรวมแนวคิดที่ดีจากพวกเขาว่าพวกเขาต้องการอินเทอร์เฟซทำอะไร

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

และในส่วนของการประชดนั้นอยู่ในนั้น หาก ใคร ควรเข้าใจวิธีสร้าง Web API ที่ใช้งานง่าย ก็คือ คุณ . ท้ายที่สุด คุณเป็นวิศวกรซอฟต์แวร์เช่นเดียวกับผู้ใช้ API ของคุณ คุณจึงแบ่งปันมุมมองของพวกเขาได้ ไม่ได้คุณ?

ในขณะที่คุณ เข้าใจ มุมมองของพวกเขาอย่างแน่นอน คุณไม่จำเป็นต้อง แบ่งปัน มุมมองของพวกเขา เมื่อคุณกำลังพัฒนาหรือปรับปรุง API ของ คุณ คุณมีมุมมองของ นักออกแบบ API ในขณะที่พวกเขามีมุมมองของ ผู้ใช้ API

นักออกแบบ API มักเน้นที่คำถามเช่น "บริการนี้ต้องทำอะไร" หรือ “บริการนี้จำเป็นต้องจัดหาอะไรบ้าง” ในขณะที่ ผู้ใช้ API ให้ความสำคัญกับ "ฉันจะใช้ API นี้เพื่อทำสิ่งที่ฉันต้องการได้อย่างไร" หรือแม่นยำกว่านั้น "ฉันจะใช้ความพยายามขั้นต่ำสุดเพื่อให้ได้สิ่งที่ต้องการจาก API นี้ได้อย่างไร" .

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

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

จากที่กล่าวมา เรามาพูดถึง 5 Golden Rules for Designing a Great Web API กัน นั่นคือ:

1. เอกสาร
2. ความมั่นคงและความสม่ำเสมอ
3. ความยืดหยุ่น
4. ความปลอดภัย
5. ง่ายต่อการนำไปใช้

กฎข้อที่ 1: เอกสาร

เอกสารประกอบ ใช่ ฉันกำลังเริ่มต้นที่นี่

คุณเกลียดเอกสารหรือไม่? ฉันสามารถเห็นอกเห็นใจ แต่สวมหมวก "มุมมองผู้ใช้" ของคุณและฉันจะเดิมพันว่าสิ่งหนึ่งที่คุณเกลียดมากกว่าต้องเขียนเอกสารคือการพยายามใช้ API ที่ไม่มีเอกสาร ฉันพักกรณีของฉัน

สิ่งสำคัญที่สุดคือ หากคุณต้องการให้ใครก็ตามใช้ API ของคุณ เอกสารประกอบก็เป็นสิ่งจำเป็น คุณเพียงแค่ต้องทำให้ถูกต้อง เป็นสิ่งแรกที่ผู้ใช้จะได้เห็น ดังนั้นในบางแง่มุม มันก็เหมือนกับการห่อของขวัญ นำเสนอได้ดี และผู้คนมีแนวโน้มที่จะใช้ API ของคุณและทนต่อความแปลกประหลาดต่างๆ ได้มากขึ้น

แล้วเราจะเขียนเอกสารที่ดีได้อย่างไร?

ส่วนที่ค่อนข้างง่ายคือการจัดทำเอกสารวิธีการ API ด้วยตนเอง กล่าวคือ ตัวอย่างคำขอและการตอบสนอง พร้อมด้วยคำอธิบายของแต่ละองค์ประกอบในทั้งสองอย่าง โชคดีที่มีเครื่องมือซอฟต์แวร์จำนวนมากขึ้นที่ช่วยอำนวยความสะดวกและทำให้งานสร้างเอกสารง่ายขึ้น หรือคุณสามารถเขียนบางสิ่งด้วยตนเองที่พินิจพิเคราะห์ API, ปลายทาง และฟังก์ชันของคุณ และสร้างเอกสารที่เกี่ยวข้องให้กับคุณ

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

ตัวอย่างเช่น หากนักพัฒนาของ Twilio แสดงรายการทุกคลาส ทุกวิธี และทุกการตอบสนองที่เป็นไปได้ต่อ API ของพวกเขา แต่ไม่ต้องพูดถึงว่าคุณสามารถส่ง SMS ติดตามการโทร หรือซื้อหมายเลขโทรศัพท์ผ่าน API ของพวกเขา ผู้ใช้ API จะใช้เวลานานมากในการค้นหาข้อมูลนั้นและทำความเข้าใจอย่างเหนียวแน่น คุณลองจินตนาการถึงการจัดเรียงต้นไม้ขนาดยักษ์ของคลาสและเมธอดโดยไม่เข้าใจว่ามันใช้ทำอะไร นอกจากชื่อของมัน ฟังดูแย่มากใช่มั้ย? แต่นั่นคือสิ่งที่ผู้ให้บริการ API จำนวนมากทำ ดังนั้นจึงปล่อยให้ API ของพวกเขาไม่ชัดเจนสำหรับทุกคนยกเว้นตัวเอง นักพัฒนา Rackspace CloudFiles และคู่มือ API เป็นตัวอย่างหนึ่ง เป็นการยากที่จะเข้าใจ เว้นแต่คุณจะเข้าใจอยู่แล้วว่าพวกเขากำลังทำอะไรและให้อะไร

ดังนั้นให้เขียนบทช่วยสอนที่กระชับซึ่งช่วยให้นักพัฒนาเริ่มทำงานได้อย่างรวดเร็ว อย่างน้อยก็มีโครงร่างของสิ่งที่พวกเขาพยายามจะทำ จากนั้นชี้ไปที่รายการฟังก์ชันการทำงานที่มีรายละเอียดและเอกสารครบถ้วนมากขึ้น เพื่อให้สามารถขยายได้ ในสิ่งที่พวกเขามี

เมื่อคุณเสร็จสิ้นกับเอกสารของคุณแล้ว อย่าลืมตรวจสอบความถูกต้องของผู้อื่นที่ไม่ใช่ตัวคุณเอง ส่งไปให้นักพัฒนาคนอื่นๆ ในเครือข่ายของคุณ ห้ามไม่ให้คำสั่งอื่นใดนอกจากชี้ไปที่เอกสารประกอบ และขอให้พวกเขาทำตามบทช่วยสอนหรือสร้างสิ่งพื้นฐานจริงๆ ในเวลาประมาณ 15 นาที หากพวกเขาไม่สามารถผสานรวมพื้นฐานกับ API ของคุณภายใน 15 นาที แสดงว่าคุณมีงานมากขึ้นที่ต้องทำ

สำหรับตัวอย่างที่น่าสังเกตของเอกสารที่ยอดเยี่ยมและมีรายละเอียด โปรดดู Twilio, Django และ MailChimp ไม่มีผลิตภัณฑ์ใดที่จำเป็นต้องดีที่สุดในตลาดของตน (แม้ว่าจะเป็นผลิตภัณฑ์ที่ดีทั้งหมด) แต่ผลิตภัณฑ์เหล่านี้สามารถแยกแยะความแตกต่างของธีมได้โดยการจัดเตรียมเอกสารที่ดีที่สุดบางส่วนภายในตลาดของตน ซึ่งช่วยอำนวยความสะดวกในการยอมรับในวงกว้างและส่วนแบ่งการตลาดได้อย่างแน่นอน

กฎข้อที่ 2: ความมั่นคงและความสม่ำเสมอ

หากคุณเคยใช้ API ของ Facebook คุณจะรู้ว่าพวกเขาเลิกใช้งานและเขียน API ใหม่ทั้งหมดบ่อยเพียงใด ไม่ว่าคุณจะเคารพวัฒนธรรมของแฮ็กเกอร์หรือผลิตภัณฑ์ของพวกเขามากเพียงใด ทัศนคติของพวกเขาก็ไม่ใช่มุมมองที่เป็นมิตรกับนักพัฒนา เหตุผลที่พวกเขายังคงประสบความสำเร็จก็เพราะมีผู้ใช้นับพันล้านคน ไม่ใช่เพราะ API ของพวกเขายอดเยี่ยม

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

สมมติว่า API ของคุณสามารถเข้าถึงได้ผ่านทาง URL http://myapisite.com/api/widgets และให้การตอบสนองในรูปแบบ JSON แม้ว่าสิ่งนี้อาจดูดีในตอนแรก จะเกิดอะไรขึ้นเมื่อคุณต้องแก้ไขรูปแบบของการตอบสนอง JSON ทุกคนที่รวมเข้ากับคุณจะแตกสลาย อ๊ะ.

ดังนั้น ให้วางแผนล่วงหน้า และกำหนดเวอร์ชัน API ของคุณตั้งแต่เริ่มต้น โดยระบุหมายเลขเวอร์ชันลงใน URL อย่างชัดเจน (เช่น http://myapisite.com/api/widgets?version=1 หรือ http://myapisite.com/api/widgets/v1 ) เพื่อให้ผู้คนสามารถพึ่งพาเวอร์ชัน 1 ที่ใช้งานได้ และสามารถอัปเกรดเป็นเวอร์ชันที่ตามมาได้เมื่อพร้อมที่จะทำเช่นนั้น หากคุณต้องการเลิกใช้เวอร์ชันก่อนหน้าในบางจุด ให้ดำเนินการ แต่แจ้งให้ทราบและเสนอแผนการเปลี่ยนแปลงบางอย่าง

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

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

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

กฎข้อที่ 3: ความยืดหยุ่น

Garbage in, garbage out (GIGO) เป็นมนต์ที่รู้จักกันดีสำหรับโปรแกรมเมอร์ส่วนใหญ่ เมื่อนำไปใช้กับการออกแบบ Web API หลักการชี้นำนี้มีแนวโน้มที่จะกำหนดแนวทางที่ค่อนข้างเข้มงวดเพื่อขอการตรวจสอบ ฟังดูดีใช่มั้ย? ไม่วุ่นวาย ไม่มีปัญหา

เช่นเดียวกับทุกสิ่งทุกอย่าง จะต้องมีความสมดุลอยู่บ้าง เนื่องจากเป็นไปไม่ได้ที่จะคาดเดาทุกวิถีทางที่ผู้ใช้จะต้องการใช้บริการของคุณ และเนื่องจากไม่ใช่ทุกแพลตฟอร์มไคลเอนต์จะสอดคล้องกัน (เช่น ไม่ใช่ทุกแพลตฟอร์มที่มีการรองรับ JSON ที่ดีมาก ไลบรารี OAuth ที่ดี ฯลฯ) จึงเป็นข้อดี มีความยืดหยุ่นหรือความอดทนอย่างน้อยในระดับหนึ่งเกี่ยวกับข้อจำกัดอินพุตและเอาต์พุตของคุณ

ตัวอย่างเช่น API จำนวนมากจะรองรับรูปแบบเอาต์พุตที่หลากหลาย เช่น JSON, YAML, XML และอื่นๆ al. แต่จะสนับสนุนเฉพาะการระบุรูปแบบใน URL เท่านั้น ในแง่ของความยืดหยุ่น คุณสามารถอนุญาตให้ระบุสิ่งนี้ใน URL (เช่น /api/v1/widgets.json ) หรือคุณอาจอ่านและรู้จักส่วนหัว Accept: application/json HTTP หรือสนับสนุน a ตัวแปรสตริงการสืบค้น เช่น ?format=JSON เป็นต้น

และในขณะที่เรากำลังดำเนินการอยู่ เหตุใดจึงไม่อนุญาตรูปแบบที่ระบุให้คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ เพื่อให้ผู้ใช้สามารถระบุ ?format=json ได้เช่นกัน นั่นเป็นตัวอย่างคลาสสิกของวิธีการบรรเทาความหงุดหงิดที่ไม่จำเป็นสำหรับผู้ใช้ API ของคุณ

อีกตัวอย่างหนึ่งคือการอนุญาตให้ป้อนตัวแปรด้วยวิธีต่างๆ ดังนั้น เช่นเดียวกับที่คุณมีรูปแบบเอาต์พุตที่หลากหลาย อนุญาตให้ใช้รูปแบบอินพุตที่หลากหลายเช่นกัน (เช่น ตัวแปร POST ธรรมดา, JSON, XML เป็นต้น) อย่างน้อยคุณควรสนับสนุนตัวแปร POST มาตรฐาน และแอปพลิเคชั่นที่ทันสมัยจำนวนมากรองรับ JSON เช่นกัน ดังนั้นทั้งสองจึงเป็นจุดเริ่มต้นที่ดี

ประเด็นคือคุณไม่ควรทึกทักเอาเองว่าทุกคนมีความชอบทางเทคนิคของคุณเหมือนกัน ด้วยการค้นคว้าเพียงเล็กน้อยเกี่ยวกับวิธีการทำงานของ API อื่นๆ และผ่านการโต้ตอบกับนักพัฒนารายอื่น คุณจะสามารถรวบรวมทางเลือกที่มีประโยชน์อื่นๆ ที่เป็นประโยชน์และรวมไว้ใน API ของคุณ

กฎข้อที่ 4: ความปลอดภัย

เห็นได้ชัดว่าการรักษาความปลอดภัยเป็นหนึ่งในสิ่งที่สำคัญที่สุดในการสร้างบริการเว็บของคุณ แต่นักพัฒนาจำนวนมากทำให้มันใช้งานยากอย่างน่าขัน ในฐานะผู้ให้บริการ API คุณควรนำเสนอตัวอย่างที่ใช้งานได้ของวิธีการตรวจสอบสิทธิ์และการอนุญาตเมื่อเข้าถึง API ของคุณ สิ่งนี้ไม่ควรเป็นปัญหายากที่ผู้ใช้ปลายทางใช้เวลาทำงานหลายชั่วโมง ทำให้เป็นเป้าหมายของคุณว่าพวกเขาไม่ต้องเขียนโค้ดใดๆ หรือใช้เวลาน้อยกว่า 5 นาทีในการเขียน

สำหรับ API ส่วนใหญ่ ฉันชอบการรับรองความถูกต้องโดยใช้โทเค็นอย่างง่าย โดยที่โทเค็นนั้นเป็นแฮชแบบสุ่มที่กำหนดให้กับผู้ใช้ และสามารถรีเซ็ตได้ทุกเมื่อหากถูกขโมย อนุญาตให้ส่งโทเค็นผ่าน POST หรือส่วนหัว HTTP ตัวอย่างเช่น ผู้ใช้สามารถ (และควร) ส่งโทเค็น SHA-1 เป็นตัวแปร POST หรือเป็นส่วนหัวในรูปแบบเช่น “Authorization: da39a3ee5e6b4b0d3255bfef95601890afd80709”

นอกจากนี้ ให้เลือกโทเค็นที่ปลอดภัย ไม่ใช่ตัวระบุตัวเลขแบบสั้น สิ่งที่ไม่สามารถย้อนกลับได้ดีที่สุด ตัวอย่างเช่น การสร้างโทเค็น SHA ระหว่างการสร้างผู้ใช้และจัดเก็บไว้ในฐานข้อมูลนั้นค่อนข้างง่าย จากนั้น คุณสามารถสืบค้นฐานข้อมูลของคุณสำหรับผู้ใช้ที่ตรงกับโทเค็นนั้น คุณยังสามารถสร้างโทเค็นที่สร้างด้วยตัวระบุที่ไม่ซ้ำกันและค่าเกลือ เช่น SHA(User.ID + "abcd123") จากนั้นค้นหาผู้ใช้ที่ตรงกัน เช่น โดย where TokenFromPost = SHA(User.ID + "abcd123")

อีกตัวเลือกที่ดีมากคือ OAuth 2 + SSL คุณควรใช้ SSL อยู่ดี แต่ OAuth 2 นั้นใช้งานง่ายพอสมควรในฝั่งเซิร์ฟเวอร์ และไลบรารี่ก็พร้อมใช้งานสำหรับภาษาโปรแกรมทั่วไปหลายภาษา

หาก API ที่คุณสร้างขึ้นควรสามารถเข้าถึงได้บนเว็บไซต์สาธารณะผ่าน JavaScript คุณต้องตรวจสอบให้แน่ใจว่าคุณตรวจสอบรายการ URL ต่อบัญชีสำหรับโทเค็น ด้วยวิธีนี้จะไม่มีใครสามารถตรวจสอบการเรียก API ของคุณ ขโมยโทเค็นจากผู้ใช้ของคุณ และนำไปใช้ด้วยตนเองได้

สิ่งสำคัญอื่นๆ ที่ควรทราบมีดังนี้

• ฟังก์ชันไวท์ลิสต์ โดยทั่วไป API ช่วยให้คุณสร้าง อ่าน อัปเดต และลบข้อมูลพื้นฐานได้ แต่คุณไม่ต้องการให้การดำเนินการเหล่านี้กับทุกเอนทิตี ดังนั้นตรวจสอบให้แน่ใจว่าแต่ละรายการมีรายการที่อนุญาตพิเศษของการดำเนินการที่อนุญาต ตรวจสอบให้แน่ใจว่าเฉพาะผู้ใช้ที่ได้รับอนุญาตเท่านั้นที่สามารถเรียกใช้คำสั่งเช่น /user/delete/<id> ในทำนองเดียวกัน ส่วนหัวที่เป็นประโยชน์ทั้งหมดที่ส่งในคำขอของผู้ใช้ต้องได้รับการตรวจสอบกับรายการที่อนุญาตด้วยเช่นกัน หากคุณอนุญาตส่วนหัวของประเภทเนื้อหา ให้ตรวจสอบว่าสิ่งที่ผู้ใช้ส่งเข้ามาตรงกับรายการประเภทเนื้อหาที่รองรับจริงหรือไม่ หากไม่เป็นเช่นนั้น ให้ส่งข้อความแสดงข้อผิดพลาดกลับ เช่น 406 Not Acceptable response การอนุญาตพิเศษมีความสำคัญเนื่องจาก API จำนวนมากถูกสร้างขึ้นโดยอัตโนมัติ หรือใช้บัญชีดำแทน ซึ่งหมายความว่าคุณต้องมีความชัดเจนเกี่ยวกับสิ่งที่คุณ ไม่ ต้องการ อย่างไรก็ตาม กฎทองของการรักษาความปลอดภัยคือการเริ่มต้นโดยไม่มีอะไรสมบูรณ์ และอนุญาตเฉพาะสิ่งที่ คุณ ต้องการอย่างชัดเจนเท่านั้น

• ป้องกันตัวเองจากการปลอมแปลงคำขอข้ามไซต์ (CSRF) หากคุณอนุญาตให้ตรวจสอบสิทธิ์เซสชันหรือคุกกี้ คุณต้องตรวจสอบให้แน่ใจว่าคุณกำลังป้องกันตัวเองจากการโจมตี CSRF โครงการ Open Web Application Security (OWASP) ให้คำแนะนำที่เป็นประโยชน์เกี่ยวกับวิธีการป้องกันช่องโหว่เหล่านี้

• ตรวจสอบการเข้าถึงทรัพยากร ในทุกคำขอ คุณต้องตรวจสอบว่าผู้ใช้ได้รับอนุญาตให้เข้าถึงรายการเฉพาะที่พวกเขากำลังอ้างอิงอยู่จริงหรือไม่ ดังนั้น หากคุณมีปลายทางเพื่อดูรายละเอียดบัตรเครดิตของผู้ใช้ (เช่น /account/card/view/152423 ) ตรวจสอบให้แน่ใจว่า ID “152423” อ้างอิงถึงทรัพยากรที่ผู้ใช้ได้รับอนุญาตให้เข้าถึงจริงๆ

• ตรวจสอบอินพุตทั้งหมด อินพุตทั้งหมดจากผู้ใช้ต้องได้รับการแยกวิเคราะห์อย่างปลอดภัย ควรใช้ไลบรารีที่เป็นที่รู้จักหากคุณใช้อินพุตที่ซับซ้อน เช่น XML หรือ JSON อย่าสร้าง parser ของคุณเอง มิฉะนั้นคุณอยู่ในโลกแห่งความเจ็บปวด

กฎข้อที่ 5: ความง่ายในการยอมรับ

นี่เป็นกฎที่สำคัญที่สุดในกลุ่ม และต่อยอดจากกฎเกณฑ์อื่นๆ ทั้งหมด ดังที่ได้กล่าวไว้ในกฎของเอกสาร ให้ลองใช้กับผู้ที่ยังใหม่กับ API ของคุณ ตรวจสอบให้แน่ใจว่าพวกเขาสามารถเริ่มต้นและใช้งาน API ของคุณได้อย่างน้อย แม้ว่าจะเป็นเพียงการปฏิบัติตามบทช่วยสอนก็ตาม ภายในไม่กี่นาที ผมคิดว่า 15 นาทีเป็นประตูที่ดี

ต่อไปนี้คือคำแนะนำเฉพาะบางประการเพื่อบรรเทาและอำนวยความสะดวกในการปรับใช้ API ของคุณ:

• ตรวจสอบให้แน่ใจว่าผู้คนสามารถใช้ API ของคุณได้จริงและใช้งานได้ในครั้งแรก ทุกครั้ง ให้คนใหม่ลองใช้ API ของคุณเป็นครั้งคราวเพื่อตรวจสอบว่าไม่มีความสับสนในบางวิธีที่คุณมีภูมิคุ้มกันต่อ

• ง่าย ๆ เข้าไว้. อย่าทำการรับรองความถูกต้องใด ๆ อย่าใช้รูปแบบ URL ที่กำหนดเองอย่างบ้าคลั่ง อย่าคิดค้น SOAP หรือ JSON หรือ REST หรืออะไรก็ตาม ใช้เครื่องมือทั้งหมดที่คุณทำได้ซึ่งมีการใช้งานแล้วและเป็นที่ยอมรับในวงกว้าง เพื่อให้นักพัฒนาต้องเรียนรู้ API ของคุณเท่านั้น ไม่ใช่เทคโนโลยีใหม่ที่ไม่ชัดเจนของ API + 10

• จัดเตรียมไลบรารีเฉพาะภาษาเพื่อเชื่อมต่อกับบริการของคุณ มีเครื่องมือดีๆ บางอย่างในการสร้างห้องสมุดให้คุณโดยอัตโนมัติ เช่น Alpaca หรือ Apache Thrift ปัจจุบัน Alpaca รองรับ Node, PHP, Python และ Ruby Thrift รองรับ C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml, Delphi และอีกมากมาย

• ลดความซับซ้อนของการสมัครที่จำเป็น หากคุณไม่ได้กำลังพัฒนา API แบบโอเพนซอร์ส หรือมีกระบวนการสมัครใช้งานในลักษณะใดก็ตาม ตรวจสอบให้แน่ใจว่าเมื่อสมัครใช้งาน ผู้ใช้จะถูกนำไปที่บทช่วยสอนอย่างรวดเร็ว และทำให้ขั้นตอนการสมัครเป็นแบบอัตโนมัติโดยไม่จำเป็นต้องมีปฏิสัมพันธ์กับมนุษย์ในส่วนของคุณ

• ให้การสนับสนุนที่ดีเยี่ยม อุปสรรคสำคัญในการนำไปใช้คือการขาดการสนับสนุน คุณจะจัดการและตอบสนองต่อรายงานข้อบกพร่องอย่างไร แล้วเอกสารไม่ชัดเจนล่ะ? ผู้ใช้ที่ไม่ซับซ้อน? ฟอรัม ตัวติดตามจุดบกพร่อง และการสนับสนุนทางอีเมลเป็นจุดเริ่มต้นที่ยอดเยี่ยม แต่อย่าลืมว่าเมื่อมีคนโพสต์ข้อบกพร่อง คุณจะต้องจัดการกับปัญหานั้นจริงๆ ไม่มีใครอยากเห็นฟอรัมเมืองร้างหรือรายการแมลงขนาดยักษ์ที่ยังไม่ได้รับการแก้ไข

สรุป Web API

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

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