Làm cách nào để thiết kế tìm kiếm / lọc RESTful? [đóng cửa]

Tôi hiện đang thiết kế và triển khai API RESTful trong PHP. Tuy nhiên, tôi đã không thành công khi thực hiện thiết kế ban đầu của mình.

GET /users # list of users
GET /user/1 # get user with id 1
POST /user # create new user
PUT /user/1 # modify user with id 1
DELETE /user/1 # delete user with id 1

Cho đến nay khá chuẩn, phải không?

Vấn đề của tôi là với cái đầu tiên GET /users. Tôi đã xem xét việc gửi các tham số trong cơ thể yêu cầu để lọc danh sách. Điều này là do tôi muốn có thể chỉ định các bộ lọc phức tạp mà không cần url siêu dài, như:

GET /users?parameter1=value1&parameter2=value2&parameter3=value3&parameter4=value4

Thay vào đó tôi muốn có một cái gì đó như:

GET /users
# Request body:
{
    "parameter1": "value1",
    "parameter2": "value2",
    "parameter3": "value3",
    "parameter4": "value4"
}

dễ đọc hơn nhiều và cung cấp cho bạn các khả năng tuyệt vời để đặt các bộ lọc phức tạp.

Dù sao, file_get_contents('php://input')đã không trả lại cơ thể GETyêu cầu cho các yêu cầu. Tôi cũng đã thử http_get_request_body(), nhưng lưu trữ chia sẻ mà tôi đang sử dụng không có pecl_http. Không chắc nó sẽ giúp được gì.

Tôi đã tìm thấy câu hỏi này và nhận ra rằng GET có lẽ không cần phải có một cơ quan yêu cầu. Đó là một chút không kết luận, nhưng họ khuyên chống lại nó.

Vì vậy, bây giờ tôi không biết phải làm gì. Làm thế nào để bạn thiết kế một chức năng tìm kiếm / lọc RESTful?

Tôi cho rằng tôi có thể sử dụng POST, nhưng điều đó không có vẻ rất RESTful.

Cách tốt nhất để thực hiện tìm kiếm RESTful là coi chính tìm kiếm đó là một tài nguyên. Sau đó, bạn có thể sử dụng động từ POST vì bạn đang tạo một tìm kiếm. Bạn không cần phải tạo một cái gì đó trong cơ sở dữ liệu để sử dụng POST.

Ví dụ:

Accept: application/json
Content-Type: application/json
POST http://example.com/people/searches
{
  "terms": {
    "ssn": "123456789"
  },
  "order": { ... },
  ...
}

Bạn đang tạo một tìm kiếm từ quan điểm của người dùng. Các chi tiết thực hiện này là không liên quan. Một số API RESTful thậm chí có thể không cần sự kiên trì. Đó là một chi tiết thực hiện.

Nếu bạn sử dụng phần thân yêu cầu trong yêu cầu GET, bạn sẽ vi phạm nguyên tắc REST, vì yêu cầu GET của bạn sẽ không thể được lưu vào bộ đệm, vì hệ thống bộ đệm chỉ sử dụng URL.

Và điều tồi tệ hơn là URL của bạn không thể được đánh dấu, vì URL không chứa tất cả thông tin cần thiết để chuyển hướng người dùng đến trang này

Sử dụng tham số URL hoặc Truy vấn thay vì tham số thân yêu cầu.

ví dụ:

/myapp?var1=xxxx&var2=xxxx
/myapp;var1=xxxx/resource;var2=xxxx 

Trên thực tế, HTTP RFC 7231 nói rằng:

Một tải trọng trong một thông báo yêu cầu GET không có ngữ nghĩa được xác định; gửi một cơ quan tải trọng theo yêu cầu GET có thể khiến một số triển khai hiện có từ chối yêu cầu.

Để biết thêm thông tin hãy xem tại đây

Dường như việc lọc / tìm kiếm tài nguyên có thể được thực hiện theo cách RESTful. Ý tưởng là để giới thiệu một điểm cuối mới được gọi là /filters/hoặc /api/filters/.

Sử dụng bộ lọc điểm cuối này có thể được coi là một tài nguyên và do đó được tạo thông qua POSTphương thức. Bằng cách này - tất nhiên - cơ thể có thể được sử dụng để mang tất cả các tham số cũng như các cấu trúc tìm kiếm / bộ lọc phức tạp có thể được tạo.

Sau khi tạo bộ lọc như vậy, có hai khả năng để có kết quả tìm kiếm / bộ lọc.

1. Một tài nguyên mới với ID duy nhất sẽ được trả về cùng với 201 Createdmã trạng thái. Sau đó, sử dụng ID này, một GETyêu cầu có thể được thực hiện /api/users/như sau:

   GET /api/users/?filterId=1234-abcd
   

2. Sau khi bộ lọc mới được tạo thông qua POSTnó sẽ không trả lời 201 Creatednhưng cùng một lúc 303 SeeOthervới Locationtiêu đề trỏ đến /api/users/?filterId=1234-abcd. Chuyển hướng này sẽ được tự động xử lý thông qua thư viện cơ bản.

Trong cả hai trường hợp, hai yêu cầu cần phải được thực hiện để có kết quả được lọc - điều này có thể được coi là một nhược điểm, đặc biệt đối với các ứng dụng di động. Đối với các ứng dụng di động, tôi sẽ sử dụng một POSTcuộc gọi đến /api/users/filter/.

Làm thế nào để giữ các bộ lọc được tạo?

Chúng có thể được lưu trữ trong DB và được sử dụng sau này. Chúng cũng có thể được lưu trữ trong một số lưu trữ tạm thời, ví dụ như redis và có một số TTL sau đó chúng sẽ hết hạn và sẽ bị xóa.

Những lợi thế của ý tưởng này là gì?

Các bộ lọc, kết quả được lọc có thể lưu trong bộ nhớ cache và thậm chí có thể được đánh dấu.

Tôi nghĩ bạn nên đi với các tham số yêu cầu nhưng chỉ khi không có tiêu đề HTTP phù hợp để thực hiện những gì bạn muốn làm. Đặc tả HTTP không nói rõ ràng rằng GET không thể có phần thân. Tuy nhiên , bài viết này nêu:

Theo quy ước, khi phương thức GET được sử dụng, tất cả thông tin cần thiết để xác định tài nguyên được mã hóa trong URI. Không có quy ước nào trong HTTP / 1.1 về tương tác an toàn (ví dụ: truy xuất) trong đó máy khách cung cấp dữ liệu cho máy chủ trong cơ thể thực thể HTTP thay vì trong phần truy vấn của URI. Điều này có nghĩa là đối với các hoạt động an toàn, URI có thể dài.

Khi tôi đang sử dụng một phụ trợ laravel / php, tôi có xu hướng đi với một cái gì đó như thế này:

/resource?filters[status_id]=1&filters[city]=Sydney&page=2&include=relatedResource

PHP tự động biến []params thành một mảng, vì vậy trong ví dụ này tôi sẽ kết thúc với một $filterbiến chứa một mảng / đối tượng của các bộ lọc, cùng với một trang và bất kỳ tài nguyên liên quan nào tôi muốn tải.

Nếu bạn sử dụng ngôn ngữ khác, đây vẫn có thể là một quy ước tốt và bạn có thể tạo một trình phân tích cú pháp để chuyển đổi []thành một mảng.

Đừng băn khoăn quá nhiều nếu API ban đầu của bạn có đầy đủ RESTful hay không (đặc biệt khi bạn chỉ ở giai đoạn alpha). Lấy hệ thống ống nước back-end để làm việc đầu tiên. Bạn luôn có thể thực hiện một số loại chuyển đổi / viết lại URL để ánh xạ mọi thứ, tinh chỉnh lặp đi lặp lại cho đến khi bạn có được thứ gì đó đủ ổn định để thử nghiệm rộng rãi ("beta").

Bạn có thể xác định các URI có tham số được mã hóa theo vị trí và quy ước trên chính các URI, được tiền tố bởi một đường dẫn mà bạn biết bạn sẽ luôn ánh xạ tới thứ gì đó. Tôi không biết PHP, nhưng tôi sẽ cho rằng một cơ sở như vậy tồn tại (vì nó tồn tại trong các ngôn ngữ khác có khung web):

.I E. Thực hiện loại tìm kiếm "người dùng" với param [i] = value [i] cho i = 1..4 trên cửa hàng số 1 (với value1, value2, value3, ... làm tốc ký cho các tham số truy vấn URI):

1) GET /store1/search/user/value1,value2,value3,value4

hoặc là

2) GET /store1/search/user,value1,value2,value3,value4

hoặc như sau (mặc dù tôi sẽ không đề xuất nó, nhiều hơn về điều đó sau)

3) GET /search/store1,user,value1,value2,value3,value4

Với tùy chọn 1, bạn ánh xạ tất cả các URI có tiền tố /store1/search/uservào trình xử lý tìm kiếm (hoặc bất kỳ ký hiệu PHP nào) để thực hiện tìm kiếm các tài nguyên trong store1 (tương đương với /search?location=store1&type=user.

Theo quy ước được tài liệu hóa và thi hành bởi API, các giá trị tham số 1 đến 4 được phân tách bằng dấu phẩy và được trình bày theo thứ tự đó.

Tùy chọn 2 thêm loại tìm kiếm (trong trường hợp này user) làm tham số vị trí # 1. Hoặc là lựa chọn chỉ là một sự lựa chọn mỹ phẩm.

Tùy chọn 3 cũng có thể, nhưng tôi không nghĩ rằng tôi sẽ thích nó. Tôi nghĩ rằng khả năng tìm kiếm trong một số tài nguyên nhất định phải được trình bày trong chính URI trước chính tìm kiếm đó (như thể chỉ ra rõ ràng trong URI rằng tìm kiếm là cụ thể trong tài nguyên.)

Ưu điểm của việc vượt qua các tham số trên URI là tìm kiếm là một phần của URI (do đó coi tìm kiếm là tài nguyên, tài nguyên có nội dung có thể - và sẽ - thay đổi theo thời gian.) Nhược điểm là thứ tự tham số là bắt buộc .

Khi bạn làm một cái gì đó như thế này, bạn có thể sử dụng GET và đó sẽ là tài nguyên chỉ đọc (vì bạn không thể POST hoặc PUT cho nó - nó sẽ được cập nhật khi nó được GET). Nó cũng sẽ là một tài nguyên chỉ tồn tại khi nó được gọi.

Người ta cũng có thể thêm nhiều ngữ nghĩa cho nó bằng cách lưu trữ các kết quả trong một khoảng thời gian hoặc với XÓA khiến bộ đệm bị xóa. Tuy nhiên, điều này có thể chạy ngược lại với những gì mọi người thường sử dụng XÓA cho (và vì mọi người thường kiểm soát bộ đệm ẩn với các tiêu đề bộ đệm.)

Làm thế nào bạn đi về nó sẽ là một quyết định thiết kế, nhưng đây sẽ là cách tôi đi. Nó không hoàn hảo và tôi chắc chắn sẽ có trường hợp thực hiện điều này không phải là điều tốt nhất để làm (đặc biệt đối với các tiêu chí tìm kiếm rất phức tạp).

FYI: Tôi biết điều này hơi muộn nhưng đối với bất kỳ ai quan tâm. Phụ thuộc vào mức độ RESTful mà bạn muốn trở thành, bạn sẽ phải thực hiện các chiến lược lọc của riêng mình vì thông số HTTP không rõ ràng về điều này. Tôi muốn đề xuất mã hóa url tất cả các tham số bộ lọc, vd

GET api/users?filter=param1%3Dvalue1%26param2%3Dvalue2

Tôi biết điều đó thật xấu xí nhưng tôi nghĩ đó là cách RESTful nhất để làm điều đó và nên dễ dàng phân tích về phía máy chủ :)