วิธี RESTful ที่ดีที่สุดในการคืนจำนวนรายการทั้งหมดในวัตถุคืออะไร

ฉันกำลังพัฒนาบริการ REST API สำหรับเว็บไซต์เครือข่ายสังคมขนาดใหญ่ที่ฉันเข้าร่วมจนถึงตอนนี้มันใช้งานได้ดี ฉันสามารถออกGET, POST, PUTและDELETEการร้องขอไปยัง URL ที่วัตถุและส่งผลกระทบต่อข้อมูลของฉัน อย่างไรก็ตามข้อมูลนี้ได้รับการเพจ (จำกัด ผลลัพธ์ได้ครั้งละ 30 รายการ)

อย่างไรก็ตามวิธีที่ดีที่สุดในการได้รับจำนวนสมาชิกทั้งหมดผ่าน API ของฉันคืออะไร

ขณะนี้ฉันส่งคำขอไปยังโครงสร้าง URL ดังต่อไปนี้:

• / api / members— ส่งคืนรายชื่อสมาชิก (ครั้งละ 30 รายการตามที่กล่าวไว้ข้างต้น)
• / api / members / 1 -มีผลต่อสมาชิกเดี่ยวขึ้นอยู่กับวิธีการร้องขอที่ใช้

คำถามของฉันคือฉันจะใช้โครงสร้าง URL ที่คล้ายกันเพื่อรับจำนวนสมาชิกทั้งหมดในใบสมัครของฉันได้อย่างไร เห็นได้ชัดว่าขอเพียงidฟิลด์ (คล้ายกับกราฟ API ของ Facebook) และการนับผลลัพธ์จะไม่ได้ผลเนื่องจากมีเพียง 30 รายการเท่านั้นที่จะถูกส่งคืน

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

StackOverflow API เป็นตัวอย่างที่ดีของการออกแบบเดียวกัน นี่คือเอกสารสำหรับวิธีการผู้ใช้ - https://api.stackexchange.com/docs/users

ฉันชอบใช้ HTTP Headers สำหรับข้อมูลบริบทประเภทนี้

สำหรับองค์ประกอบทั้งหมดฉันใช้X-total-countส่วนหัว
สำหรับลิงก์ไปยังหน้าถัดไปหน้าก่อนหน้า ฯลฯ ฉันใช้Linkส่วนหัวhttp :
http://www.w3.org/wiki/LinkHeader

Github ทำเช่นเดียวกัน: https://developer.github.com/v3/#pagination

ในความคิดของฉันมันสะอาดกว่าเพราะมันสามารถใช้ได้เมื่อคุณส่งคืนเนื้อหาที่ไม่สนับสนุนไฮเปอร์ลิงก์ (เช่นไบนารีรูปภาพ)

_{ฉันได้ทำการวิจัยอย่างกว้างขวางเกี่ยวกับเรื่องนี้และคำถามอื่น ๆ ที่เกี่ยวข้องกับการเพจเพจเมื่อเร็ว ๆ นี้และคิดว่ามันสร้างสรรค์เพื่อเพิ่มสิ่งที่ฉันค้นพบที่นี่ ฉันกำลังขยายคำถามเล็กน้อยเพื่อรวมความคิดเกี่ยวกับการเพจเช่นเดียวกับการนับที่เกี่ยวข้องอย่างใกล้ชิด}

ส่วนหัว

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

มีส่วนหัว (มาตรฐานและกำหนดเอง) ที่ใช้ใน wild เพื่อส่งคืนข้อมูลที่เกี่ยวข้องกับการเพจรวมถึงจำนวนทั้งหมด

X-รวม-Count

X-Total-Count: 234

สิ่งนี้ใช้ในAPI บางตัวที่ พบใน wild นอกจากนี้ยังมีแพ็คเกจ NPMสำหรับเพิ่มการสนับสนุนสำหรับส่วนหัวนี้เช่น Loopback บางบทความแนะนำให้ตั้งค่าส่วนหัวนี้ด้วย

มันมักจะใช้ร่วมกับLinkส่วนหัวซึ่งเป็นวิธีที่ดีสำหรับเพจจิ้ง แต่ขาดข้อมูลการนับทั้งหมด

ลิงค์

Link: </TheBook/chapter2>;
      rel="previous"; title*=UTF-8'de'letztes%20Kapitel,
      </TheBook/chapter4>;
      rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel

ฉันรู้สึกจากการอ่านมากเกี่ยวกับเรื่องนี้ว่ามติทั่วไปคือการใช้Linkส่วนหัวเพื่อให้เพจเชื่อมโยงไปยังลูกค้าที่ใช้rel=next, rel=previousฯลฯ ปัญหานี้ก็คือว่ามันขาดข้อมูลของระเบียนทั้งหมดหลายวิธีที่มีซึ่งเป็น เหตุใด API จำนวนมากจึงรวมสิ่งนี้กับX-Total-Countส่วนหัว

อีกวิธีหนึ่งคือ API บางตัวและมาตรฐานJsonApiใช้Linkรูปแบบ แต่เพิ่มข้อมูลในซองจดหมายตอบกลับแทนที่จะเป็นส่วนหัว ทำให้การเข้าถึงข้อมูลเมตา (และสร้างสถานที่เพื่อเพิ่มข้อมูลการนับทั้งหมด) ทำได้โดยเสียค่าใช้จ่ายในการเพิ่มความซับซ้อนในการเข้าถึงข้อมูลจริงเอง (โดยการเพิ่มซองจดหมาย)

เนื้อหาช่วง

Content-Range: items 0-49/234

โปรโมตโดยบทความบล็อกชื่อส่วนหัว Range ฉันเลือกคุณ (สำหรับการแบ่งหน้า)! . ผู้เขียนทำให้กรณีที่แข็งแกร่งสำหรับการใช้RangeและContent-Rangeส่วนหัวสำหรับการแบ่งหน้า เมื่อเราอ่านอย่างละเอียดRFCบนส่วนหัวเหล่านี้เราจะพบว่าการขยายความหมายของพวกเขาเกินกว่าช่วงของไบต์ที่คาดว่าจะจริงโดย RFC และจะได้รับอนุญาตอย่างชัดเจน เมื่อใช้ในบริบทแทนที่จะเป็นส่วนหัวช่วงให้เราทั้งสองวิธีขอรายการบางช่วงและระบุช่วงของผลรวมที่รายการตอบกลับเกี่ยวข้อง ส่วนหัวนี้ยังเป็นวิธีที่ยอดเยี่ยมในการแสดงจำนวนรวม และเป็นมาตรฐานที่แท้จริงซึ่งส่วนใหญ่จะแมปแบบหนึ่งต่อหนึ่งกับการเพจ นอกจากนี้ยังใช้ในป่า itemsbytes

ซองจดหมาย

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

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

จุดปลายแยก

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

ความคิดเพิ่มเติม

เราไม่เพียง แต่ต้องสื่อสารข้อมูลเมตาเพจจิ้งที่เกี่ยวข้องกับการตอบสนอง แต่ยังอนุญาตให้ลูกค้าขอหน้า / ช่วงที่เฉพาะเจาะจง เป็นที่น่าสนใจที่จะพิจารณามุมมองนี้เพื่อหาทางออกที่สอดคล้องกัน ที่นี่เราสามารถใช้ส่วนหัว ( Rangeส่วนหัวที่ดูเหมือนว่าเหมาะสมมาก) หรือกลไกอื่น ๆ เช่นพารามิเตอร์แบบสอบถาม บางคนสนับสนุนการรักษาหน้าของผลเป็นทรัพยากรที่แยกต่างหากซึ่งอาจทำให้ความรู้สึกในกรณีการใช้งานบางอย่าง (เช่น/books/231/pages/52. ฉันจบลงด้วยการเลือกช่วงป่าของพารามิเตอร์คำขอที่ใช้บ่อยเช่นpagesize, page[size]และlimitฯลฯ ในนอกเหนือจากการสนับสนุนRangeส่วนหัว (และเป็นพารามิเตอร์คำขอ เช่นกัน)

ทางเลือกเมื่อคุณไม่ต้องการรายการจริง

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

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

/api/members?metaonly=true
/api/members?includeitems=0

หรือสิ่งที่คล้ายกัน ...

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

(หรือหากคุณอยู่ในสภาพแวดล้อมที่มีการควบคุมตั้งแต่ปลายทางจนถึงปลายทางคุณสามารถใช้กริยา HTTP แบบกำหนดเองเช่น COUNT)

ฉันขอแนะนำให้เพิ่มส่วนหัวเหมือนกันเช่น:

HTTP/1.1 200

Pagination-Count: 100
Pagination-Page: 5
Pagination-Limit: 20
Content-Type: application/json

[
  {
    "id": 10,
    "name": "shirt",
    "color": "red",
    "price": "$23"
  },
  {
    "id": 11,
    "name": "shirt",
    "color": "blue",
    "price": "$25"
  }
]

สำหรับรายละเอียดอ้างอิงถึง:

https://github.com/adnan-kamili/rest-api-response-format

สำหรับไฟล์วางท่า:

https://github.com/adnan-kamili/swagger-response-template

ในฐานะของ "X -" - คำนำหน้าถูกคัดค้าน (ดู: https://tools.ietf.org/html/rfc6648 )

เราพบว่า "ยอมรับช่วง" เป็นทางออกที่ดีที่สุดในการแมปเลขหน้า: https://tools.ietf.org/html/rfc7233#section-2.3 เนื่องจาก "ช่วงหน่วย" อาจเป็น "ไบต์" หรือ " โทเค็น" ทั้งสองไม่ได้เป็นตัวแทนของชนิดข้อมูลที่กำหนดเอง (ดู: https://tools.ietf.org/html/rfc7233#section-4.2 ) ถึงกระนั้นก็มีการระบุไว้ว่า

การประยุกต์ใช้ HTTP / 1.1 อาจละเว้นช่วงที่ระบุโดยใช้หน่วยอื่น

ซึ่งบ่งชี้ว่า: การใช้หน่วยช่วงที่กำหนดเองนั้นไม่ได้ขัดแย้งกับโปรโตคอล แต่อาจถูกละเว้น

ด้วยวิธีนี้เราจะต้องตั้งค่าช่วงรับเป็น "สมาชิก" หรือประเภทหน่วยใด ๆ ก็ตามที่เราคาดหวัง และนอกจากนี้ยังตั้งค่า Content-Range เป็นช่วงปัจจุบัน (ดู: https://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.12 )

ไม่ว่าจะด้วยวิธีใดฉันจะทำตามคำแนะนำของ RFC7233 ( https://tools.ietf.org/html/rfc7233#page-8 ) เพื่อส่ง 206 แทน 200:

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

ดังนั้นเราจะมีฟิลด์ส่วนหัว HTTP ต่อไปนี้:

สำหรับเนื้อหาบางส่วน:

206 Partial Content
Accept-Ranges: members
Content-Range: members 0-20/100

สำหรับเนื้อหาเต็ม:

200 OK
Accept-Ranges: members
Content-Range: members 0-20/20

ดูเหมือนง่ายที่สุดที่จะเพิ่ม

GET
/api/members/count

และส่งคืนจำนวนสมาชิกทั้งหมด

จุดสิ้นสุดใหม่> / api / members / count ซึ่งเพิ่งเรียก Members.Count () และส่งกลับผลลัพธ์

บางครั้งเฟรมเวิร์ก (เช่น $ resource / AngularJS) จำเป็นต้องมีอาร์เรย์เป็นผลลัพธ์แบบสอบถามและคุณไม่สามารถตอบสนองได้{count:10,items:[...]}ในกรณีนี้ฉันเก็บ "count" ไว้ใน responseHeaders

PS ที่จริงคุณสามารถทำได้ด้วย $ resource / AngularJS แต่ต้องการการปรับแต่ง

คุณสามารถพิจารณาcountsเป็นทรัพยากร URL นั้นจะเป็น:

/api/counts/member

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

ฉันชอบที่จะมีจุดปลายแยกต่างหากสำหรับการนับ (หรือจุดสิ้นสุดเดียวกันกับพารามิเตอร์ countOnly) เนื่องจากคุณสามารถเตรียมผู้ใช้สำหรับกระบวนการที่ใช้เวลานาน / โดยแสดงแถบความคืบหน้าที่เริ่มต้นอย่างถูกต้อง

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

<data>
  <originalRequest>
    <filter/>
    <filter/>
  </originalReqeust>
  <totalRecordCount/>
  <pageSize/>
  <offset/>
  <list>
     <item/>
     <item/>
  </list>
</data>

Couleage of Mine ต้องการพารามิเตอร์ countOnly ให้กับจุดปลายที่มีอยู่ ดังนั้นเมื่อระบุการตอบสนองจะมีข้อมูลเมตาเท่านั้น

ปลายทาง? = ค่าตัวกรอง

<data>
  <count/>
  <list>
    <item/>
    ...
  </list>
</data>

ปลายทาง? กรอง value = & countOnly = true

<data>
  <count/>
  <!-- empty list -->
  <list/>
</data>