THIẾT KẾ API REST - Nhận tài nguyên thông qua REST với các tham số khác nhau nhưng cùng một mẫu url

Tôi có một câu hỏi liên quan đến thiết kế url REST. Tôi đã tìm thấy một số bài đăng có liên quan ở đây: Các đại diện RESTful khác nhau của cùng một tài nguyên và tại đây: RESTful url để GET tài nguyên theo các trường khác nhau nhưng các phản hồi không hoàn toàn rõ ràng về các phương pháp hay nhất là gì và tại sao. Đây là một ví dụ.

Tôi có các url REST để đại diện cho tài nguyên "người dùng". Tôi có thể NHẬN người dùng có id hoặc địa chỉ email nhưng cách trình bày URL vẫn giống nhau cho cả hai. Xem qua rất nhiều blog và sách, tôi thấy rằng mọi người đã và đang làm điều này theo nhiều cách khác nhau. Ví dụ

đọc thực hành này trong một cuốn sách và ở đâu đó trên stackoverflow (dường như tôi không thể tìm thấy liên kết lại)

GET /users/id={id}
GET /users/email={email}

đọc thực hành này trên nhiều blog

GET /users/{id}
GET /users/email/{email}

Tham số truy vấn thường được sử dụng để lọc kết quả của các tài nguyên được đại diện bởi url, nhưng tôi đã thấy phương pháp này cũng được sử dụng

GET /users?id={id}
GET /users?email={email}

Câu hỏi của tôi là, trong số tất cả các phương pháp này, phương pháp nào sẽ có ý nghĩa nhất đối với các nhà phát triển sử dụng apis và tại sao? Tôi tin rằng không có quy tắc nào được đặt ra khi nói đến thiết kế url REST và quy ước đặt tên, nhưng tôi chỉ muốn biết mình nên thực hiện theo lộ trình nào để giúp các nhà phát triển hiểu rõ hơn về apis.

Tất cả sự trợ giúp được đánh giá cao!

Theo kinh nghiệm của tôi, GET /users/{id} GET /users/email/{email}là cách tiếp cận phổ biến nhất. Tôi cũng mong đợi các phương thức trả về 404 Not Found nếu người dùng không tồn tại với idhoặc được cung cấp email. Tôi cũng sẽ không ngạc nhiên khi thấy GET /users/id/{id}(mặc dù theo ý kiến ​​của tôi, nó là thừa).

Nhận xét về các cách tiếp cận khác

1. GET /users/id={id} GET /users/email={email}
   • Tôi không nghĩ rằng tôi đã thấy điều này, và nếu tôi đã nhìn thấy nó, nó sẽ rất khó hiểu. Nó gần giống như nó đang cố gắng bắt chước các tham số truy vấn với các tham số đường dẫn.
2. GET /users?id={id} GET /users?email={email}
   • Tôi nghĩ rằng bạn đã đánh vào đầu khi bạn đề cập đến việc sử dụng các tham số truy vấn để lọc.
   • Có bao giờ nên gọi tài nguyên này bằng cả dấu idvà email(ví dụ GET /users?id={id}&email={email}) không? Nếu không, tôi sẽ không sử dụng một phương pháp tài nguyên đơn lẻ như thế này.
   • Tôi mong chờ phương pháp này để lấy một danh sách của người sử dụng với các thông số truy vấn tùy chọn để lọc, nhưng tôi sẽ không mong đợi id, emailhoặc bất kỳ định danh duy nhất là một trong các thông số. Ví dụ: GET /users?status=BANNEDcó thể trả về danh sách người dùng bị cấm.

_{Kiểm tra câu trả lời này từ một câu hỏi liên quan.}

Nhìn vào điều này một cách thực dụng, bạn có một tập hợp người dùng:

/users   # this returns many

Mỗi người dùng có một vị trí tài nguyên dành riêng:

/users/{id}    # this returns one

Bạn cũng có một số cách để tìm kiếm người dùng:

/users?email={email}
/users?name=*bob*

Vì đây là tất cả các tham số truy vấn cho / người dùng, tất cả chúng sẽ trả về danh sách .. ngay cả khi đó là danh sách 1.

Tôi đã viết một bài đăng trên blog về thiết kế API RESTful thực dụng ở đây nói về điều này, trong số những thứ khác, tại đây: http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api

Giới thiệu về tài nguyên người dùng

trên đường dẫn, /usersbạn sẽ luôn nhận được một tập hợp các tài nguyên người dùng được trả về.

trên con đường /users/[user_id]bạn có thể mong đợi một số điều sẽ xảy ra:

1. bạn sẽ nhận được một tài nguyên singleton đại diện cho tài nguyên người dùng với số nhận dạng của nó [user_id] hoặc
2. không tìm thấy phản hồi 404 nếu không có người dùng nào có id [user_id] tồn tại hoặc
3. 401 bị cấm nếu bạn không được phép truy cập tài nguyên người dùng được yêu cầu.

Mỗi singleton được xác định duy nhất bởi đường dẫn và mã định danh của nó và bạn sử dụng chúng để tìm tài nguyên. Không thể sử dụng một số đường dẫn cho singleton.

Bạn có thể truy vấn đường dẫn /usersbằng các tham số truy vấn ( GETParameters). Thao tác này sẽ trả về một bộ sưu tập với những người dùng đáp ứng các tiêu chí được yêu cầu. Bộ sưu tập được trả về phải chứa tài nguyên người dùng, tất cả đều có đường dẫn tài nguyên nhận dạng của họ trong phản hồi.

Tham số có thể là bất kỳ trường nào có trong tài nguyên của bộ sưu tập; firstName, lastName,id

Về email

Email có thể là tài nguyên hoặc thuộc tính / trường của tài nguyên người dùng.

- Email là tài sản của người dùng:

Nếu trường là thuộc tính của người dùng thì phản hồi của người dùng sẽ trông giống như sau:

{ 
  id: 1,
  firstName: 'John'
  lastName: 'Doe'
  email: 'john.doe@example.com'
  ...
}

Điều này có nghĩa không có thiết bị đầu cuối đặc biệt cho email, nhưng bây giờ bạn có thể tìm thấy một người dùng qua email của mình bằng cách gửi yêu cầu sau đây: /users?email=john.doe@example.com. Cái nào (giả sử email là duy nhất cho người dùng) sẽ trả về một bộ sưu tập có một mục người dùng khớp với email.

- Email như một tài nguyên:

Nhưng nếu email từ người dùng cũng là tài nguyên. Sau đó, bạn có thể tạo một API để /users/[user_id]/emailstrả về một tập hợp các địa chỉ email cho người dùng có id user_id. /users/[user_id]/emails/[email_id]trả về email của người dùng với user_id và ['email_id']. Những gì bạn sử dụng làm số nhận dạng là tùy thuộc vào bạn, nhưng tôi sẽ gắn bó với một số nguyên. Bạn có thể xóa email khỏi người dùng bằng cách gửi DELETEyêu cầu đến đường dẫn xác định email bạn muốn xóa. Vì vậy, ví dụ DELETEtrên /users/[user_id]/emails/[email_id]sẽ xóa email có email_id được sở hữu bởi người dùng với user_id. Nhiều khả năng chỉ người dùng đó mới được phép thực hiện thao tác xóa này. Những người dùng khác sẽ nhận được phản hồi 401.

Nếu người dùng chỉ có thể có một địa chỉ email, bạn có thể gắn vào /users/[user_id]/email Điều này trả về một tài nguyên đơn lẻ. Người dùng có thể cập nhật địa chỉ email của mình bằng cách PUTnhập địa chỉ email tại url đó.