RESTful API ฉันควรส่งคืนวัตถุที่สร้าง / อัพเดทหรือไม่

ฉันกำลังออกแบบเว็บเซอร์วิส RESTful โดยใช้ WebApi และสงสัยว่าการตอบสนอง HTTP และร่างกายการตอบสนองที่จะกลับมาเมื่อมีการปรับปรุง / สร้างวัตถุ

ตัวอย่างเช่นฉันสามารถใช้วิธีการโพสต์เพื่อส่ง JSON บางส่วนไปยังบริการเว็บแล้วสร้างวัตถุ เป็นวิธีที่ดีที่สุดหรือไม่ที่จะตั้งค่าสถานะ HTTP เป็นสร้าง (201) หรือตกลง (200) และเพียงแค่ส่งคืนข้อความเช่น "เพิ่มพนักงานใหม่" หรือส่งคืนวัตถุที่ถูกส่งมาตั้งแต่แรก?

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

ความคิดใด ๆ

ตัวอย่าง:

เพิ่มพนักงานใหม่:

POST /api/employee HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
    "Employee": {
        "Name" : "Joe Bloggs",
        "Department" : "Finance"
    }
}

อัพเดทพนักงานที่มีอยู่:

PUT /api/employee HTTP/1.1
Host: localhost:8000
Content-Type: application/json

{
    "Employee": {
        "Id" : 1
        "Name" : "Joe Bloggs",
        "Department" : "IT"
    }
}

คำตอบ:

การตอบสนองกับวัตถุที่สร้าง / อัพเดท

HTTP/1.1 201 Created
Content-Length: 39
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Mar 2016 14:32:39 GMT

{
    "Employee": {
        "Id" : 1
        "Name" : "Joe Bloggs",
        "Department" : "IT"
    }
}

การตอบสนองด้วยข้อความเพียง:

HTTP/1.1 200 OK
Content-Length: 39
Content-Type: application/json; charset=utf-8
Date: Mon, 28 Mar 2016 14:32:39 GMT

{
    "Message": "Employee updated"
}

การตอบสนองด้วยรหัสสถานะเพียง:

HTTP/1.1 204 No Content
Content-Length: 39
Date: Mon, 28 Mar 2016 14:32:39 GMT

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

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

ส่วนตัวผมมักจะ200 OKกลับมาเท่านั้น

เพื่ออ้างคำถามของคุณ

พิจารณาข้อเท็จจริงที่ว่าผู้ใช้รู้ว่าวัตถุใดที่พวกเขากำลังพยายามสร้าง / อัปเดตอยู่ดี

ทำไมต้องเพิ่มแบนด์วิดท์เพิ่มเติม (ซึ่งอาจต้องจ่าย) เพื่อบอกลูกค้าว่ามันรู้อะไรไปแล้ว?

@ iswinky ฉันจะส่ง payload กลับมาเสมอในกรณีของ POST และ PUT

ในกรณีของ POST คุณอาจสร้างเอนทิตีที่มี ID ภายในหรือ UUID ดังนั้นจึงเหมาะสมที่จะส่ง payload กลับ

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

การส่งคืนข้อมูลตามที่ได้รับการยืนยันเป็นความคิดที่ดีเสมอและไม่เป็นอันตรายอย่างแน่นอน หากผู้เรียกไม่ต้องการข้อมูลที่ส่งคืนนี้เขา / เธอจะไม่ประมวลผล แต่จะใช้ statusCode มิฉะนั้นพวกเขาสามารถใช้ข้อมูลนี้เป็นสิ่งที่จะอัปเดต UI ด้วย

เฉพาะในกรณีของการลบที่ฉันจะไม่ส่งคืนน้ำหนักบรรทุกและจะทำอย่างใดอย่างหนึ่ง 200 กับเนื้อหาการตอบสนองหรือ 204 ที่ไม่มีเนื้อหาการตอบสนอง

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

ก) เมื่อฉันบอกว่าส่งคืนน้ำหนักบรรทุกฉันหมายถึงส่งข้อมูลของทรัพยากรกลับไม่ใช่น้ำหนักบรรทุกเดียวกันที่มาในคำขอ ตัวอย่าง: ถ้าคุณส่ง payload ในการสร้างฉันอาจจะสร้างเอนทิตี้อื่น ๆ เช่นแบ็กเอนด์ UUID และ (อาจ) timestamps และการเชื่อมต่อบางอย่าง (กราฟ) ฉันจะส่งกลับทั้งหมดนี้ในการตอบสนอง (ไม่เพียง แต่น้ำหนักบรรทุกตามคำขอ - ซึ่งไม่มีจุดหมาย)

b) ฉันจะไม่ส่งการตอบกลับในกรณีที่ส่วนของข้อมูลมีขนาดใหญ่มาก ฉันได้พูดถึงเรื่องนี้ในความคิดเห็น แต่สิ่งที่ฉันต้องการที่จะเตือนคือฉันจะพยายามอย่างดีที่สุดในการออกแบบ API หรือทรัพยากรของฉันเพื่อที่มันจะได้ไม่ต้องมีส่วนของข้อมูลขนาดใหญ่มาก ฉันจะพยายามแบ่งทรัพยากรออกเป็นเอนทิตีที่เล็กลงและสามารถจัดการได้ซึ่งทรัพยากรแต่ละอย่างจะถูกกำหนดโดยแอ็ตทริบิวต์ JSON 15-20 และไม่ใหญ่กว่า

ในกรณีที่วัตถุมีขนาดใหญ่มากหรือวัตถุแม่กำลังได้รับการปรับปรุงแล้วฉันจะส่งกลับโครงสร้างที่ซ้อนกันเป็น hrefs

บรรทัดล่างคือฉันจะพยายามส่งข้อมูลที่เหมาะสมสำหรับผู้บริโภค / UI ในการประมวลผลทันทีและดำเนินการกับแอ็คชั่นอะตอมมิก API แทนที่จะต้องไปแล้วดึง API เพิ่มเติมอีก 2-5 เพื่ออัปเดตโพสต์ UI การสร้าง / อัพเดทข้อมูล

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

อ้างอิงถึงลิงก์RFC มาตรฐานคุณควรส่งคืนสถานะ 201 (สร้าง) เมื่อเก็บทรัพยากรคำขอเรียบร้อยแล้วโดยใช้โพสต์ ในแอปพลิเคชันส่วนใหญ่ id ของทรัพยากรถูกสร้างขึ้นโดยเซิร์ฟเวอร์เองดังนั้นจึงเป็นการดีที่จะส่งคืนรหัสของทรัพยากรที่สร้างขึ้น การส่งคืนวัตถุทั้งหมดเป็นค่าใช้จ่ายสำหรับคำขอโพสต์ แนวปฏิบัติที่เหมาะสมคือส่งคืนตำแหน่ง URLของทรัพยากรที่สร้างขึ้นใหม่

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

@RequestMapping(path = "/employees", method = RequestMethod.POST)
public ResponseEntity<Object> saveEmployee(@RequestBody Employee employee) {
        int id = employeeService.saveEmployee(employee);
        URI uri = ServletUriComponentsBuilder.fromCurrentRequest().path("/{id}").buildAndExpand(id).toUri();
        return ResponseEntity.created(uri).build();
}

จุดสิ้นสุดส่วนที่เหลือนี้จะส่งคืนการตอบกลับเป็น:

สถานะ 201 - สร้างแล้ว

ตำแหน่งส่วนหัว→ http: // localhost: 8080 / พนักงาน / 1

ฉันจะทำให้น้ำหนักบรรทุกในร่างกายกลับมาตามเงื่อนไขกับพารามิเตอร์ HTTP

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

ตามความเป็นจริงเมื่อแอปพลิเคชันของเรามีการใช้ข้อมูลมากขึ้นและกระจายมากขึ้นฉันลองปฏิบัติตามแนวทางนี้:

คำแนะนำของฉัน :

เมื่อใดก็ตามที่มีกรณีการใช้งานที่ต้องการ GET ทันทีหลังจาก POST หรือ PUT นั่นคือกรณีที่อาจเป็นการดีที่สุดที่จะส่งคืนบางสิ่งในการตอบสนอง POST / PUT

วิธีดำเนินการนี้และเนื้อหาประเภทใดที่จะส่งคืนกลับมาจาก PUT หรือ POST นั่นเป็นแอปพลิเคชันเฉพาะ ตอนนี้มันจะน่าสนใจถ้าแอปพลิเคชันสามารถกำหนดประเภทของ "เนื้อหา" ในเนื้อหาการตอบสนอง (เราต้องการเพียงตำแหน่งของวัตถุใหม่หรือบางส่วนของเขตข้อมูลหรือวัตถุทั้งหมด ฯลฯ )

แอปพลิเคชันสามารถกำหนดชุดของพารามิเตอร์ที่ POST / PUT สามารถรับเพื่อควบคุมประเภทของ "เนื้อหา" เพื่อส่งคืนในเนื้อหาการตอบสนอง หรืออาจเข้ารหัสเคียวรี GraphQL บางประเภทเป็นพารามิเตอร์ (ฉันเห็นว่านี่มีประโยชน์ แต่ก็กลายเป็นฝันร้ายการบำรุงรักษาด้วย)

ไม่ว่าจะด้วยวิธีใดดูเหมือนฉันว่า:

1. มันก็โอเค (และเป็นที่ต้องการมากที่สุด) เพื่อส่งคืนบางสิ่งในเนื้อความการตอบสนอง POST / PUT
2. วิธีการนี้ทำขึ้นเฉพาะแอปพลิเคชันและแทบจะเป็นไปไม่ได้ที่จะพูดคุยทั่วไป
3. คุณไม่ต้องการส่งคืน "บริบท" ขนาดใหญ่เป็นค่าเริ่มต้น (เสียงรบกวนการจราจรที่เอาชนะเหตุผลทั้งหมดของการย้ายออกจาก POST-follow-by-GETs)

ดังนั้น 1) ทำ แต่ 2) ทำให้มันง่าย

ตัวเลือกอื่นที่ฉันได้เห็นคือคนที่สร้างจุดสิ้นสุดทางเลือก (เช่น / ลูกค้าสำหรับ POST / PUT ที่ไม่ส่งคืนอะไรในร่างกายและ / customer_with_details สำหรับ POST / PUT ถึง / ลูกค้า แต่กลับมาบางสิ่งในเนื้อความการตอบกลับ)

ฉันจะหลีกเลี่ยงวิธีการนี้ได้ จะเกิดอะไรขึ้นเมื่อคุณต้องกลับเนื้อหาประเภทอื่นอย่างถูกกฎหมาย? จุดปลายเดียวต่อประเภทเนื้อหาหรือไม่ ไม่สามารถปรับขนาดหรือบำรุงรักษาได้