URL ของคุณมีลักษณะอย่างไรกับ REST อะไรจะไป จริงๆแล้วมันคือ "รายละเอียดการใช้งาน" เช่นเดียวกับที่คุณตั้งชื่อตัวแปรของคุณ สิ่งที่พวกเขาจะต้องมีความโดดเด่นและคงทน
อย่าเสียเวลากับเรื่องนี้มากนักเพียงแค่เลือกและทำตาม / ให้สอดคล้องกัน ตัวอย่างเช่นถ้าคุณไปกับลำดับชั้นแล้วคุณทำเพื่อทรัพยากรทั้งหมดของคุณ ถ้าคุณไปกับพารามิเตอร์การสืบค้น ... ฯลฯ เช่นเดียวกับการตั้งชื่อการประชุมในรหัสของคุณ
ทำไมเป็นเช่นนั้น เท่าที่ฉันทราบ API "RESTful" จะสามารถเรียกดูได้ (คุณรู้ว่า ... "Hypermedia ในฐานะ Engine of Application State") ดังนั้นไคลเอ็นต์ API ไม่สนใจว่า URL ของคุณจะเป็นอย่างไรตราบใดที่ URL นั้น ถูกต้อง (ไม่มี SEO, ไม่มีมนุษย์คนใดที่จำเป็นต้องอ่าน "URL ที่เป็นมิตร" เหล่านั้นยกเว้นอาจใช้เพื่อการดีบัก ... )
ความดี / ความเข้าใจของ URL ที่อยู่ใน REST API นั้นน่าสนใจสำหรับคุณในฐานะนักพัฒนา API ไม่ใช่ลูกค้า API เช่นเดียวกับชื่อของตัวแปรในรหัสของคุณ
สิ่งที่สำคัญที่สุดคือลูกค้า API ของคุณรู้วิธีตีความประเภทสื่อของคุณ ตัวอย่างเช่นรู้ว่า:
- ประเภทสื่อของคุณมีคุณสมบัติลิงก์ที่แสดงรายการลิงก์ที่เกี่ยวข้อง / มีอยู่
- แต่ละลิงก์ถูกระบุโดยความสัมพันธ์ (เช่นเดียวกับเบราว์เซอร์รู้ว่าลิงก์ [rel = "stylesheet"] หมายถึงสไตล์ชีทหรือ rel = favico เป็นลิงค์ไปยัง favicon ... )
- และรู้ว่าความสัมพันธ์เหล่านั้นมีความหมายอย่างไร ("บริษัท " หมายถึงรายชื่อ บริษัท "ค้นหา" หมายถึง URL ของ templated สำหรับการค้นหาในรายการทรัพยากร "แผนก" หมายถึงแผนกของทรัพยากรปัจจุบัน)
ด้านล่างเป็นตัวอย่างการแลกเปลี่ยน HTTP (เนื้อความอยู่ใน yaml เนื่องจากง่ายต่อการเขียน):
ขอร้อง
GET / HTTP/1.1
Host: api.acme.io
Accept: text/yaml, text/acme-mediatype+yaml
การตอบสนอง:รายการลิงก์ไปยังทรัพยากรหลัก (บริษัท ผู้คนอะไรก็ตาม ... )
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:04:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: this is your API's entrypoint (like a homepage)
links:
# could be some random path https://api.acme.local/modskmklmkdsml
# the only thing the API client cares about is the key (or rel) "companies"
companies: https://api.acme.local/companies
people: https://api.acme.local/people
คำขอ:ลิงก์ไปยัง บริษัท ต่างๆ (โดยใช้ body.links.com การตอบกลับก่อนหน้านี้)
GET /companies HTTP/1.1
Host: api.acme.local
Accept: text/yaml, text/acme-mediatype+yaml
การตอบสนอง:รายการบางส่วนของ บริษัท (ภายใต้รายการ) ทรัพยากรมีลิงค์ที่เกี่ยวข้องเช่นลิงก์เพื่อรับคู่ของ บริษัท ถัดไป (body.links.next) ลิงก์อื่น (templated) เพื่อค้นหา (body.links.search)
HTTP/1.1 200 OK
Date: Tue, 05 Apr 2016 15:06:00 GMT
Last-Modified: Tue, 05 Apr 2016 00:00:00 GMT
Content-Type: text/acme-mediatype+yaml
# body: representation of a list of companies
links:
# link to the next page
next: https://api.acme.local/companies?page=2
# templated link for search
search: https://api.acme.local/companies?query={query}
# you could provide available actions related to this resource
actions:
add:
href: https://api.acme.local/companies
method: POST
items:
- name: company1
links:
self: https://api.acme.local/companies/8er13eo
# and here is the link to departments
# again the client only cares about the key department
department: https://api.acme.local/companies/8er13eo/departments
- name: company2
links:
self: https://api.acme.local/companies/9r13d4l
# or could be in some other location !
department: https://api2.acme.local/departments?company=8er13eo
ดังนั้นตามที่คุณเห็นถ้าคุณไปที่ลิงค์ / วิธีการที่คุณจัดโครงสร้างเส้นทางส่วนของ URL ของคุณไม่มีค่าใด ๆ ให้กับลูกค้า API ของคุณ และหากคุณกำลังสื่อสารโครงสร้างของ URL ไปยังลูกค้าของคุณเป็นเอกสารแสดงว่าคุณไม่ได้ทำ REST (หรืออย่างน้อยไม่ใช่ระดับ 3 ตาม " โมเดลวุฒิภาวะของ Richardson ")