เคล็ดลับ 5 ข้อในการสร้าง RESTful APIs ติดกับ JSON
ในทางเทคนิค REST API ไม่ได้จำกัดให้ทำงานกับไฟล์ประเภทเดียวเท่านั้น REST API สามารถใช้ไฟล์ XML และ SOAP เป็นต้น เพียงเพราะคุณไม่สามารถ หมายความว่าคุณ ควรแม้ว่า ตามหลักการทั่วไป JSON ควรเป็นรูปแบบมาตรฐานสำหรับการส่งและรับข้อมูลด้วย API เกือบทุกรูปแบบเว็บสามารถใช้ได้สำหรับสิ่งหนึ่ง ส่วนใหญ่มีวิธีจัดการกับ JSON ในตัว เกือบทุกนักพัฒนาเว็บทำเช่นกัน นั่นเป็นเหตุผลเพียงพอที่จะเลือก JSON เหนือรูปแบบอื่นๆ ได้ทุกเมื่อที่ทำได้
รูปแบบไฟล์อื่นๆ มักต้องการการประมวลผลภายนอกเพิ่มเติม ไฟล์ XML มักจะต้องแปลงเป็น JSON ก่อนจึงจะสามารถใช้งานได้ ตัวอย่างเช่น การจัดการข้อมูล XML ในฝั่งไคลเอ็นต์ยังทำได้ยากกว่า
เพื่อให้แน่ใจว่าคุณกำลังทำงานกับ JSON อยู่เสมอ คุณสามารถระบุประเภทไฟล์โดยการตั้งค่าContent-typeตัวแปรในส่วนหัวของการตอบกลับapplication/jsonเมื่อมีการร้องขอ แอพบางตัวตั้งค่าส่วนหัวการตอบกลับเป็น JSON โดยอัตโนมัติในขณะที่ต้องระบุในส่วนอื่น คุณจะต้องแน่ใจว่าปลายทาง API ของคุณส่งคืนไฟล์ JSON
ลองมาดูกันว่าสิ่งนี้มีลักษณะอย่างไรในการดำเนินการ นี่คือตัวอย่างการทำงานกับเฟรมเวิร์กเว็บ Expressซึ่งจะแยกวิเคราะห์คำขอโดยใช้body-parserฟังก์ชัน วัตถุผลลัพธ์จะถูกเรียกโดยใช้res.json.
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());
app.post('/', (req, res) => {
res.json(req.body);
});
app.listen(3000, () => console.log('server started'));แยกbodyParser.json()วิเคราะห์คำขอ JSON เป็นออบเจ็กต์ JavaScript ซึ่งระบุแหล่งที่มาจากreq.bodyอ็อบเจ็กต์
ในการตอบกลับ ให้ตั้งค่าContent-typeส่วนหัวapplication/json; charset=utf-8เป็น วิธีนี้ควรใช้ได้กับกรอบงานเว็บส่วนใหญ่
สิ่งของ ไม่ใช่การกระทำ
โปรดจำไว้ว่า ปลายทาง API ควรจัดหมวดหมู่เพื่อให้การดำเนินการทั้งหมดเกิดขึ้นที่ฝั่งแบบสอบถาม เมื่อคำนึงถึงสิ่งนี้ คุณควรตั้งชื่อปลายทางของคุณตามวัตถุไม่ใช่สิ่งที่เกิดขึ้นกับสิ่งเหล่านั้น ซึ่งอาจทำให้บางโปรแกรมตีความว่าเป็นโค้ดโดยไม่ได้ตั้งใจ
ลองนึกภาพว่าคุณต้องการดึงข้อมูลรถทั้งหมดจากฐานข้อมูลรถ ตอนนี้ ลองจินตนาการว่าคุณส่งคืนผลลัพธ์ทั้งหมดเหล่านั้นไปยังจุดgetCarsสิ้นสุด
รูปแบบการตั้งชื่อเดียวกันนั้นใช้สำหรับวัตถุใน JavaScript อย่างไรก็ตาม ไม่มีการบอกชนิดของความหายนะที่ข้อผิดพลาดง่าย ๆ ดังกล่าวสามารถเกิดขึ้นได้
ตามหลักการทั่วไป ตั้งชื่อปลายทาง API ของคุณเป็นคำนามแทนคำกริยา หากคุณต้องการระบุหรือแบ่งย่อยเพิ่มเติม คุณสามารถจัดการกับส่วนย่อยเพิ่มเติมได้
ใช้ชื่อตรรกะสำหรับปลายทาง
เหตุผลหลักประการหนึ่งสำหรับการใช้ API คือการทำให้การโต้ตอบกับข้อมูลของเราสามารถจัดการได้มากขึ้น เราจะสูญเสียข้อได้เปรียบนี้หากเราสร้างปลายทางมากเกินไปจนถึงจุดที่ยากต่อการติดตาม
ตัวอย่างเช่น สมมติว่าคุณกำลังดูแลคลังสินค้าอะไหล่รถยนต์ ลองนึกภาพว่าคุณมีปลายทางสำหรับสินค้าทุกประเภทที่คุณพกติดตัว อีกไม่นาน คุณมี `/carHeadrests’, ‘truckSeatbeltEnclosures’, ‘carRadialTires’ และอื่นๆ จะใช้เวลาไม่นานในการควบคุมจำนวนปลายทาง
ตอนนี้ให้พิจารณาทางเลือกนี้ คุณมีจุดสิ้นสุดหนึ่งจุดสำหรับยานพาหนะแต่ละประเภท ดังนั้น/trucks, /carsและอื่น ๆ จากนั้นคุณสามารถมีชิ้นส่วนสำหรับรถแต่ละประเภทเป็นไดเร็กทอรีย่อย: /cars/parts/seatbelts, /trucks/tires/whitewalls, และอื่นๆ ซึ่งช่วยให้สามารถจัดการจำนวนปลายทางได้ นอกจากนี้ยังยึดตามโครงสร้างที่เข้าใจได้ง่ายซึ่งนำทางและใช้งานง่าย ซึ่งช่วยให้ API ของคุณปฏิบัติตามหลักการของ Roy Fielding ที่ว่า API ควรจะอธิบายตนเองได้ โดยไม่ต้องใช้เอกสารจากภายนอก
เมื่อใดก็ตามที่เป็นไปได้ คุณควรพยายามและจัดกลุ่มข้อมูลที่เกี่ยวข้องเป็นปลายทางเดียว นี่เป็นความคิดที่ดีไม่ว่าฐานข้อมูลของคุณจะถูกตั้งค่าคอนฟิกอย่างไร อันที่จริง อาจเป็นความคิดที่ดีที่จะใช้โครงสร้างอื่นสำหรับปลายทาง API และฐานข้อมูลของคุณ สิ่งนี้สามารถป้องกันไม่ให้อาชญากรไซเบอร์ได้รับข้อมูลมากเกินไปเกี่ยวกับสถาปัตยกรรมระบบของคุณ
ปลายทางเหล่านี้สามารถโต้ตอบด้วย คำสั่ง GET, POST, PUTและDELETEHTTP ปกติของคุณ การสร้าง API Design
ใช้รหัสข้อผิดพลาดมาตรฐาน
เหตุผลหลักอีกประการหนึ่งที่ผู้คนใช้ API ก็คือการทำให้ข้อมูลและเครื่องมือมีความคุ้นเคย หากคุณต้องเรียนรู้และจดจำไวยากรณ์ของเครื่องมือทุกอย่างที่คุณใช้และทุกไซต์ที่คุณเยี่ยมชม คุณจะต้องใช้เวลาทั้งหมดไปกับการสำรวจเอกสารและไฟล์ช่วยเหลือ
เป็นความคิดที่ดีที่จะยึดติดกับรหัส HTTP มาตรฐานโดยคำนึงถึงสิ่งนี้ รหัสข้อผิดพลาด HTTP ที่พบบ่อยที่สุดคือ:
- 400 คำขอไม่ถูกต้อง: การป้อนข้อมูลล้มเหลวในการตรวจสอบ
- 401 Unauthorized : ผู้ใช้ไม่ได้รับอนุญาตให้เข้าถึงทรัพยากร
- 403 Forbidden : ผู้ใช้ถูกตรวจสอบสิทธิ์แต่ไม่ได้รับอนุญาตให้เข้าถึงทรัพยากร
- 404 Not Found : ไม่พบทรัพยากร
- 500 ข้อผิดพลาดเซิร์ฟเวอร์ภายใน : ข้อผิดพลาดเซิร์ฟเวอร์ทั่วไป
- 502 Bad Gateway : ระบุการตอบสนองที่ไม่ถูกต้องจากเซิร์ฟเวอร์อื่น
- **503 บริการไม่พร้อมใช้งาน – มีบางสิ่งที่ไม่คาดคิดเกิดขึ้นที่ฝั่งเซิร์ฟเวอร์
อนุญาตการเรียงลำดับ การกรอง และการแบ่งหน้า
ฐานข้อมูลที่ API โต้ตอบด้วยอาจมีขนาดค่อนข้างใหญ่และเทอะทะได้อย่างรวดเร็ว ซึ่งหมายความว่าคุณมีความเสี่ยงที่จะครอบงำระบบของคุณหากคุณไม่ระมัดระวังเกี่ยวกับการสืบค้น API การ กรองเป็นวิธีหนึ่งในการจัดเรียงผลลัพธ์ของคุณ การ แบ่งหน้ายังช่วยให้มั่นใจได้ว่าผลลัพธ์ที่คุณได้รับสามารถส่งคืนได้ครั้งละสองสามครั้ง
สิ่งนี้ยังทำหน้าที่เป็นระบบป้องกันความผิดพลาดที่สำคัญในระบบนิเวศของ API บางครั้งการเรียก API อาจทำให้ต้องเสียเงิน ซึ่งมักถูกกำหนดโดยการใช้งาน ลองนึกภาพว่าจะเกิดอะไรขึ้นหากคุณดึงข้อมูลเทราไบต์โดยไม่ได้ตั้งใจในคำขอเดียว!
ลองดูสิ่งที่อาจมีลักษณะเป็นอย่างไรในการดำเนินการ
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
// employees data in a database
const employees = [
{ firstName: 'Jane', lastName: 'Smith', age: 20 },
//...
{ firstName: 'John', lastName: 'Smith', age: 30 },
{ firstName: 'Mary', lastName: 'Green', age: 50 },
]
app.use(bodyParser.json());
app.get('/employees', (req, res) => {
const { firstName, lastName, age } = req.query;
let results = [...employees];
if (firstName) {
results = results.filter(r => r.firstName === firstName);
}
if (lastName) {
results = results.filter(r => r.lastName === lastName);
}
if (age) {
results = results.filter(r => +r.age === +age);
}
res.json(results);
});
app.listen(3000, () => console.log('server started'));ในตัวอย่างนี้req.queryตั้งค่าพารามิเตอร์แบบสอบถาม ค่าแต่ละค่าถูกทำลายโดยใช้ไวยากรณ์การทำลายโครงสร้างของ JavaScript สุดท้าย ตัวกรองจะทำงานบนผลลัพธ์ ซึ่งจะถูกส่งกลับ
ดังนั้น หากคุณจะทำการสอบถาม/employees?lastName=Smith&age=30ก็จะส่งคืน:
[
{
"firstName": "John",
"lastName": "Smith",
"age": 30
}
]สตริงนี้สอบถามฐานข้อมูลเพื่อส่งคืนพนักงานทั้งหมดที่มีนามสกุล Smith ซึ่งมีอายุ 30 ปี คำตอบจะถูกส่งกลับพร้อมกับวัตถุ JSON
คุณยังสามารถสอบถามช่วงของผลลัพธ์ได้อีกด้วย สามารถจัดเรียงผลลัพธ์ให้แสดงผลได้หลากหลายรูปแบบเช่นกัน พิจารณาสตริงแบบสอบถามต่อไปนี้:
http://example.com/articles?sort=+author,-datepublishedส่งกลับผลลัพธ์ที่มีผู้เขียนจากน้อยไปมากและวันที่ตีพิมพ์จากมากไปน้อย
ความคิดสุดท้ายเกี่ยวกับ RESTful APIs
คำจำกัดความของ Roy Fielding เกี่ยวกับมาตรฐาน RESTเป็นหนึ่งในองค์ประกอบหลักที่ทำให้การนำ API ไปใช้อย่างแพร่หลายเป็นไปได้ตั้งแต่แรก ด้วยเหตุนี้ คำต่างๆ เช่น API, REST และ RESTful จึงมักใช้แทนกันได้ ศัพท์แสงที่มีอยู่มากมายอาจทำให้การถอดรหัสการเขียนทางเทคนิคทำได้ยาก โชคดีที่เราเพิ่งโพสต์บทความเกี่ยวกับความแตกต่างระหว่าง REST และ RESTfulหากคุณต้องการคำชี้แจงเพิ่มเติม
เช่นเดียวกับทุกสิ่งที่เกี่ยวข้องกับ REST แนวทางเหล่านี้เป็นแนวทางมากกว่ากฎที่เข้มงวดและรวดเร็ว API นั้นปรับแต่งได้ไม่จำกัด ดังนั้นแม้ท้องฟ้าจะมีขีดจำกัด เราแค่พยายามช่วยให้คุณโทรหาหมายเลขโทรศัพท์ 6 พันล้านโดยไม่ได้ตั้งใจด้วยการสอบถามโดยไม่ตั้งใจเพียงครั้งเดียว
เมื่อเห็นว่าการใช้งานและการกำหนดค่า API นั้นขึ้นอยู่กับรสนิยมเป็นส่วนใหญ่ นอกจากนี้ยังมีวิธีต่างๆ มากมายที่แทบจะไม่มีที่สิ้นสุดในการเพิ่มประสิทธิภาพ API ของคุณเพื่อประสิทธิภาพสูงสุด คุณสามารถดูบทแนะนำ REST API อื่นๆ และแนวทางปฏิบัติที่ดีที่สุด ของ API เพื่อดูแนวคิดเพิ่มเติมเกี่ยวกับวิธีการใช้ประโยชน์สูงสุดจาก API ของคุณ
ทั้งนี้บริษัทเคแอนด์โอ จึงได้มุ่งเน้นการจัดการแก้ไขปัญหา จัดการเอกสาร ด้านเอกสารขององค์กรมาอย่างยาวนาน และ ให้ความสำคัญกับด้านงานเอกสาร ต่อลูกค้าเป็นอย่างดี จนถึงปัจจุบันก็ได้ความยอมรับจากองค์กร ขนาดใหญ่ ขนาดกลาง และขนาดเล็กมากมาย จึงใคร่ขออาสาดูและปัญหาด้านเอกสารให้กับองค์กรของท่านอย่างสุดความสามารถ เพราะเราเป็นหนึ่งในธุรกิจ ระบบจัดเก็บเอกสาร ที่ท่านไว้ใจได้
สอบถามได้สบายใจทั้ง เรื่องค่าบริการ ราคา และ งบประมาณ เพราะเป็นราคาที่สุด คุ้มที่สุด
เรามีแอดมินคอยคอบคำถาม 24 ชั้วโมงที่ Line OA ให้คำปรึกษาด้านวางระบบจัดการเอกสารอิเล็กทรอนิกส์ EDMS โดยทีมงานผู้เชี่ยวชาญจาก K&O
ที่มีประสบการณ์มากว่า 15 ปี รวมถึงซอฟต์แวร์ระดับโลก ติดต่อ 0 2 – 8 6 0 – 6 6 5 9 หรือ E m a i l : c s @ k o . i n . t h
หากท่านมีความสนใจ บทความ หรือ Technology สามารถติดต่อได้ตามเบอร์ที่ให้ไว้ด้านล่างนี้
Tel.086-594-5494
Tel.095-919-6699
