Làm thế nào để thiết kế một API REST với các tiêu chí LIKE?

Question

Tôi đang thiết kế một API REST và có một thực thể cho "dân":

GET http://localhost/api/people 

Trả về một danh sách tất cả những người trong hệ thống

GET http://localhost/api/people/1 

Trả về người có id 1.

GET http://localhost/api/people?forename=john&surname=smith 

Trả về tất cả những người có tên và họ phù hợp nhưng tôi có thêm yêu cầu. Cách thực hành sạch nhất/tốt nhất là cho phép người tiêu dùng API truy xuất tất cả những người có tên bắt đầu bằng "jo" chẳng hạn.

Tôi đã nhìn thấy một số API làm như thế này:

GET http://localhost/api/people?forename=jo~&surname=smith 

nơi dấu ngã nghĩa là "mờ" trận đấu. Mặt khác, tôi đã thấy nó được triển khai với một tiêu chí hoàn toàn khác, ví dụ:

GET http://localhost/api/people?forename-startswith=jo&surname=smith 

có vẻ hơi cồng kềnh khi xem xét tôi có thể có -endswith, -contains, -soundslike (đối với một số loại đối sánh âm thanh).

Bất kỳ ai cũng có thể đề xuất kinh nghiệm hoạt động tốt hơn và cũng có bất kỳ ví dụ nào về các API REST được thiết kế tốt có chức năng tương tự.

Answer 1

AFAIK, không cách nào ở trên khá yên tĩnh. Cả hai đều dựa vào kiến ​​thức của một linh mục về phần của khách hàng về cách gọi các truy vấn (trong trường hợp đầu tiên, mẫu truy vấn và trên truy vấn thứ hai là DSL truy vấn). Trong ví dụ thứ hai, trên thực tế, API được giảm xuống chỉ với một trình bao bọc xung quanh kho dữ liệu. Như vậy, API không xác định miền máy chủ - nó là nhà cung cấp dữ liệu. Điều này trái ngược với ràng buộc máy chủ-máy chủ của REST.

Nếu bạn cần để lộ một cửa hàng dữ liệu toàn diện với tất cả các khả năng truy vấn khác nhau, bạn đã tuân theo các tiêu chuẩn đã biết mà chúng tôi có OData. OData đã được bán như REST nhưng nhiều REST-đầu có vấn đề với nó. Nhưng dù sao, vào cuối ngày nó hoạt động và các cuộc thảo luận REST thường có thể dẫn đến phân tích tê liệt.

Nếu tôi đã làm điều này, tôi có thể sẽ hạn chế API cho một trường hợp sử dụng phổ biến, vì vậy một cái gì đó giống như thứ hai mà không xác định một truy vấn DSL (do forNameStartsWith thay vì forename-startswith).

Có nói rằng, nếu bạn cần truy vấn dựa trên nhiều trường và các điều kiện khác nhau, tôi sẽ sử dụng OData.

Answer 2

Cả hai ví dụ đều sử dụng tham số truy vấn để lọc. Tôi không nghĩ rằng những thông số truy vấn này được gọi là gì hoặc nếu một số cú pháp ký tự đại diện được sử dụng.

Cả hai phương pháp đều là RESTFul như nhau.

Answer 3

IMHO nó không quan trọng nếu bạn có các kết quả mờ hoặc có -endswith -contains vv Điều quan trọng là nếu REST API của bạn cho phép phân tích dễ dàng các tham số như vậy để bạn có thể xác định hàm lấy dữ liệu từ nguồn dữ liệu của bạn (DB hoặc tệp xml, v.v.) cho phù hợp

Nếu bạn đang sử dụng PHP ... từ trải nghiệm của mình, SlimFramework là giải pháp nhẹ, dễ bắt đầu.

Answer 4

Tôi muốn giới thiệu cho bạn số OData protocol cung cấp số Query String Options. Những gì bạn đã làm là ok và tuân theo các quy ước REST.

Nhưng, giao thức OData mô tả thông số $expand và thậm chí tham số $filter. $ tiền tố này biểu thị "Tùy chọn hệ thống truy vấn" và bạn sẽ quan tâm đến người cuối cùng vì nó cho phép bạn viết URI sau:

http://services.odata.org/Northwind/Northwind.svc/Customers?$filter=tolower(CompanyName) eq 'foobar' &select=FirstName,LastName&$orderby=Name desc 

Nó cho phép bạn vượt qua SQL như dữ liệu, nó có thể là một lựa chọn tốt đẹp với những gì bạn mô tả (cả hai giải pháp đều tốt, nó chỉ là vấn đề của hương vị).