Tôi đang tìm kiếm một cách hợp lý để thể hiện các tìm kiếm dưới dạng URL RESTful.

Thiết lập: Tôi có hai mô hình, Ô tô và Nhà xe, trong đó Ô tô có thể ở trong Nhà xe. Vì vậy, các url của tôi trông giống như:

/car/xxxx
  xxx == car id
  returns car with given id

/garage/yyy
  yyy = garage id
  returns garage with given id

Một chiếc xe có thể tự tồn tại (do đó là / xe) hoặc nó có thể tồn tại trong nhà để xe. Cách tốt nhất để đại diện, nói, tất cả những chiếc xe trong một nhà để xe nhất định? Cái gì đó như:

/garage/yyy/cars     ?

Làm thế nào về sự kết hợp của những chiếc xe trong gara yyy và zzz?

Cách đúng đắn để thể hiện tìm kiếm xe ô tô với các thuộc tính nhất định là gì? Nói: cho tôi xem tất cả các dòng xe màu xanh có 4 cửa:

/car/search?color=blue&type=sedan&doors=4

hoặc nó nên là / xe thay thế?

Việc sử dụng "tìm kiếm" có vẻ không phù hợp ở đó - cách nào tốt hơn / thuật ngữ? Nó chỉ nên là:

/cars/?color=blue&type=sedan&doors=4

Các tham số tìm kiếm nên là một phần của PATHINFO hoặc QUERYSTRING?

Nói tóm lại, tôi đang tìm hướng dẫn cho thiết kế url REST mô hình chéo và tìm kiếm.

[Cập nhật] Tôi thích câu trả lời của Justin, nhưng anh ấy không bao gồm trường hợp tìm kiếm đa lĩnh vực:

/cars/color:blue/type:sedan/doors:4

hoặc điều tương tự. Chúng ta đi từ đâu

/cars/color/blue

đến trường hợp nhiều trường?

Đối với việc tìm kiếm, sử dụng truy vấn. Điều này là hoàn hảo RESTful:

/cars?color=blue&type=sedan&doors=4

Một lợi thế cho các truy vấn thông thường là chúng là tiêu chuẩn và được hiểu rộng rãi và chúng có thể được tạo từ form-get.

Các RESTful thiết kế URL khá là về hiển thị một tài nguyên dựa trên một cấu trúc (thư mục giống như cấu trúc, ngày: Sản phẩm / 2005/5/13, đối tượng và các thuộc tính của nó, ..), dấu gạch chéo /chỉ ra cấu trúc phân cấp, sử dụng -idđể thay thế.

Cấu trúc phân cấp

Tôi thích cá nhân hơn:

/garage-id/cars/car-id
/cars/car-id   #for cars not in garages

Nếu người dùng loại bỏ /car-idphần đó, nó sẽ mang lại phần carsxem trước - trực quan. Người dùng biết chính xác anh ta đang ở đâu trên cây, anh ta đang nhìn gì. Anh ta biết từ cái nhìn đầu tiên, rằng nhà để xe và xe hơi có quan hệ với nhau. /car-idcũng biểu thị rằng nó thuộc về nhau không giống nhau /car/id.

Đang tìm kiếm

Các tìm kiếm là OK vì nó là , chỉ có sở thích của bạn, những gì cần được tính đến. Phần hài hước xuất hiện khi tham gia tìm kiếm (xem bên dưới).

/cars?color=blue;type=sedan   #most prefered by me
/cars;color-blue+doors-4+type-sedan   #looks good when using car-id
/cars?color=blue&doors=4&type=sedan   #I don't recommend using &*

Hoặc về cơ bản bất cứ điều gì không phải là một dấu gạch chéo như đã giải thích ở trên.
Công thức : /cars[?;]color[=-:]blue[,;+&], * mặc dù tôi sẽ không sử dụng &dấu hiệu vì nó không thể nhận ra từ văn bản trong cái nhìn đầu tiên.

** Bạn có biết rằng việc truyền đối tượng JSON trong URI là RESTful không? **

Danh sách các lựa chọn

/cars?color=black,blue,red;doors=3,5;type=sedan   #most prefered by me
/cars?color:black:blue:red;doors:3:5;type:sedan
/cars?color(black,blue,red);doors(3,5);type(sedan)   #does not look bad at all
/cars?color:(black,blue,red);doors:(3,5);type:sedan   #little difference

tính năng có thể?

Phủ định chuỗi tìm kiếm (!)
Để tìm kiếm bất kỳ chiếc xe nào, nhưng không phải màu đen và đỏ :
?color=!black,!red
color:(!black,!red)

Tìm kiếm đã tham gia
Tìm kiếm ô tô màu đỏ hoặc màu xanh hoặc đen với 3 cửa trong nhà để xe id 1..20 hoặc 101..103 hoặc 999 nhưng không phải 5 /garage[id=1-20,101-103,999,!5]/cars[color=red,blue,black;doors=3]
Bạn có thể tạo các truy vấn tìm kiếm phức tạp hơn. (Hãy xem kết hợp thuộc tính CSS3 để biết ý tưởng khớp với các chuỗi con. Ví dụ: tìm kiếm người dùng có chứa "thanh" user*=bar.)

Phần kết luận

Dù sao, đây có thể là một phần quan trọng nhất đối với bạn, vì bạn có thể làm điều đó tuy nhiên bạn như sau khi tất cả, chỉ cần ghi nhớ rằng RESTful URI đại diện cho một cấu trúc đó là dễ hiểu ví dụ như thư mục giống như /directory/file, /collection/node/item, ngày /articles/{year}/{month}/{day}.. Và khi bạn bỏ qua bất kỳ phân đoạn cuối cùng, bạn ngay lập tức biết những gì bạn nhận được.

Vì vậy, tất cả các ký tự này được cho phép không được mã hóa :

• không được giám sát: a-zA-Z0-9_.-~
  Thông thường cho phép cả mã hóa và không được mã hóa, cả hai cách sử dụng đều tương đương nhau.
• nhân vật đặc biệt: $-_.+!*'(),
• dành riêng: ;/?:@=&
  Có thể được sử dụng không được mã hóa cho mục đích mà chúng đại diện, nếu không chúng phải được mã hóa.

• không an toàn: <>"#%{}|\^~[]`
  Tại sao không an toàn và tại sao nên mã hóa: RFC 1738 xem 2.2

  Đồng thời xem RFC 1738 # page-20 để biết thêm các lớp nhân vật.

RFC 3986 xem 2.2
Mặc dù những gì tôi đã nói trước đây, đây là một sự phân biệt phổ biến của các đồng hồ đo, có nghĩa là một số " quan trọng" hơn những cái khác.

• ký hiệu chung: :/?#[]@
• biểu đồ phụ: !$&'()*+,;=

Đọc thêm:
Phân cấp: xem 2.3 , xem
cú pháp tham số đường dẫn url 1.2.3
thuộc tính CSS3 phù hợp với
IBM: RESTful Web services - Khái niệm cơ bản
Lưu ý: RFC 1738 đã được cập nhật bởi RFC 3986

Mặc dù có các tham số trong đường dẫn có một số lợi thế, nhưng có, IMO, một số yếu tố vượt trội.

• Không phải tất cả các ký tự cần thiết cho truy vấn tìm kiếm đều được cho phép trong một URL. Hầu hết các dấu chấm câu và ký tự Unicode sẽ cần được mã hóa URL dưới dạng tham số chuỗi truy vấn. Tôi đang vật lộn với cùng một vấn đề. Tôi muốn sử dụng XPath trong URL, nhưng không phải tất cả cú pháp XPath đều tương thích với đường dẫn URI. Vì vậy, đối với các đường dẫn đơn giản, /cars/doors/driver/lock/combinationsẽ thích hợp để xác định vị trí combinationphần tử '' trong tài liệu XML của trình điều khiển. Nhưng /car/doors[id='driver' and lock/combination='1234']không thân thiện lắm.

• Có một sự khác biệt giữa việc lọc tài nguyên dựa trên một trong các thuộc tính của nó và chỉ định tài nguyên.

  Ví dụ:

  /cars/colors trả về một danh sách tất cả các màu cho tất cả các xe (tài nguyên được trả về là một tập hợp các đối tượng màu)

  /cars/colors/red,blue,green sẽ trả về một danh sách các đối tượng màu là đỏ, xanh dương hoặc xanh lục, không phải là một bộ sưu tập xe ô tô.

  Để trả lại xe, con đường sẽ là

  /cars?color=red,blue,green hoặc là /cars/search?color=red,blue,green

• Các tham số trong đường dẫn khó đọc hơn vì các cặp tên / giá trị không bị cô lập với phần còn lại của đường dẫn, không phải là cặp tên / giá trị.

Một bình luận cuối cùng. Tôi thích /garages/yyy/cars(luôn luôn là số nhiều) /garage/yyy/cars(có lẽ đó là một lỗi đánh máy trong câu trả lời ban đầu) bởi vì nó tránh thay đổi đường dẫn giữa số ít và số nhiều. Đối với các từ có thêm 's', thay đổi không quá tệ, nhưng thay đổi /person/yyy/friendsthành /people/yyycó vẻ rườm rà.

Để mở rộng câu trả lời của Peter - bạn có thể đặt Tìm kiếm tài nguyên hạng nhất:

POST    /searches          # create a new search
GET     /searches          # list all searches (admin)
GET     /searches/{id}     # show the results of a previously-run search
DELETE  /searches/{id}     # delete a search (admin)

Tài nguyên Tìm kiếm sẽ có các trường cho màu sắc, tạo mô hình, trạng thái được cắt xén, v.v. và có thể được chỉ định trong XML, JSON hoặc bất kỳ định dạng nào khác. Giống như tài nguyên Xe và Nhà để xe, bạn có thể hạn chế quyền truy cập vào Tìm kiếm dựa trên xác thực. Người dùng thường xuyên chạy cùng một Tìm kiếm có thể lưu trữ chúng trong hồ sơ của họ để họ không cần phải tạo lại. Các URL sẽ đủ ngắn để trong nhiều trường hợp chúng có thể dễ dàng giao dịch qua email. Các Tìm kiếm được lưu trữ này có thể là cơ sở của các nguồn cấp RSS tùy chỉnh, v.v.

Có nhiều khả năng sử dụng Tìm kiếm khi bạn nghĩ về chúng như tài nguyên.

Ý tưởng được giải thích chi tiết hơn trong Railscast này .

Câu trả lời của Justin có lẽ là cách để đi, mặc dù trong một số ứng dụng, có thể coi việc tìm kiếm cụ thể là tài nguyên theo cách riêng của mình, chẳng hạn như nếu bạn muốn hỗ trợ các tìm kiếm đã lưu:

/search/{searchQuery}

hoặc là

/search/{savedSearchName}

Tôi sử dụng hai cách tiếp cận để thực hiện tìm kiếm.

1) Trường hợp đơn giản nhất, để truy vấn các yếu tố liên quan và để điều hướng.

    /cars?q.garage.id.eq=1

Điều này có nghĩa, truy vấn những chiếc xe có ID nhà xe bằng 1.

Cũng có thể tạo các tìm kiếm phức tạp hơn:

    /cars?q.garage.street.eq=FirstStreet&q.color.ne=red&offset=300&max=100

Ô tô trong tất cả các gara trong FirstStreet không có màu đỏ (trang thứ 3, 100 yếu tố trên mỗi trang).

2) Các truy vấn phức tạp được coi là tài nguyên thông thường được tạo và có thể được phục hồi.

    POST /searches  => Create
    GET  /searches/1  => Recover search
    GET  /searches/1?offset=300&max=100  => pagination in search

Phần POST để tạo tìm kiếm như sau:

    {  
       "$class":"test.Car",
       "$q":{
          "$eq" : { "color" : "red" },
          "garage" : {
             "$ne" : { "street" : "FirstStreet" }
          }
       }
    }

Nó dựa trên Grails (tiêu chí DSL): http://grails.org/doc/2.4.3/ref/Domain%20Class/createCriteria.html

Đây không phải là REST. Bạn không thể xác định URI cho các tài nguyên bên trong API của mình. Điều hướng tài nguyên phải được điều khiển siêu văn bản. Sẽ tốt thôi nếu bạn muốn các URI đẹp và số lượng lớn khớp nối, nhưng đừng gọi nó là REST, vì nó vi phạm trực tiếp các ràng buộc của kiến ​​trúc RESTful.

Xem bài viết này của nhà phát minh REST.

Mặc dù tôi thích phản hồi của Justin, tôi cảm thấy nó chính xác hơn đại diện cho bộ lọc hơn là tìm kiếm. Nếu tôi muốn biết về những chiếc xe có tên bắt đầu bằng cam thì sao?

Theo cách tôi nhìn thấy, bạn có thể xây dựng nó theo cách bạn xử lý các tài nguyên cụ thể:
/ ô tô / cam *

Hoặc, bạn chỉ cần thêm nó vào bộ lọc:
/ ô tô / cửa / 4 / tên / cam * / màu / đỏ, màu xanh da trời, màu xanh lá cây

Cá nhân, tôi thích cái thứ hai hơn, tuy nhiên tôi không có nghĩa là một chuyên gia về REST (lần đầu tiên nghe nói về nó chỉ khoảng 2 tuần trước ...)

RESTful không khuyến nghị sử dụng các động từ trong URL / ô tô / tìm kiếm không được nghỉ ngơi. Cách đúng để lọc / tìm kiếm / phân trang API của bạn là thông qua Tham số truy vấn. Tuy nhiên, có thể có trường hợp khi bạn phải phá vỡ định mức. Ví dụ: nếu bạn đang tìm kiếm trên nhiều tài nguyên, thì bạn phải sử dụng cái gì đó như / search? Q = query

Bạn có thể truy cập http://saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices/ để hiểu các cách thực hành tốt nhất để thiết kế API RESTful

Ngoài ra tôi cũng sẽ đề nghị:

/cars/search/all{?color,model,year}
/cars/search/by-parameters{?color,model,year}
/cars/search/by-vendor{?vendor}

Ở đây, Searchđược coi là một nguồn tài nguyên con Cars.

Có rất nhiều lựa chọn tốt cho trường hợp của bạn ở đây. Tuy nhiên, bạn nên xem xét sử dụng cơ thể POST.

Chuỗi truy vấn là hoàn hảo cho ví dụ của bạn, nhưng nếu bạn có một cái gì đó phức tạp hơn, ví dụ như một danh sách dài các mục hoặc điều kiện boolean tùy ý, bạn có thể muốn xác định bài đăng dưới dạng tài liệu, mà khách hàng gửi qua POST.

Điều này cho phép mô tả linh hoạt hơn về tìm kiếm, cũng như tránh giới hạn độ dài URL của Máy chủ.

Lời khuyên của tôi sẽ là:

/garages
  Returns list of garages (think JSON array here)
/garages/yyy
  Returns specific garage
/garage/yyy/cars
  Returns list of cars in garage
/garages/cars
  Returns list of all cars in all garages (may not be practical of course)
/cars
  Returns list of all cars
/cars/xxx
  Returns specific car
/cars/colors
  Returns lists of all posible colors for cars
/cars/colors/red,blue,green
  Returns list of cars of the specific colors (yes commas are allowed :) )

Biên tập:

/cars/colors/red,blue,green/doors/2
  Returns list of all red,blue, and green cars with 2 doors.
/cars/type/hatchback,coupe/colors/red,blue,green/
  Same idea as the above but a lil more intuitive.
/cars/colors/red,blue,green/doors/two-door,four-door
  All cars that are red, blue, green and have either two or four doors.

Hy vọng rằng cung cấp cho bạn ý tưởng. Về cơ bản, API nghỉ ngơi của bạn sẽ dễ dàng được khám phá và sẽ cho phép bạn duyệt qua dữ liệu của mình. Một lợi thế khác khi sử dụng URL và không phải chuỗi truy vấn là bạn có thể tận dụng các cơ chế bộ đệm ẩn tồn tại trên máy chủ web cho lưu lượng HTTP.

Đây là một liên kết đến một trang mô tả các tệ nạn của các chuỗi truy vấn trong REST: http://web.archive.org/web/20070815111413/http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful

Tôi đã sử dụng bộ nhớ cache của Google vì trang bình thường cũng không hoạt động với tôi ở đây liên kết đó: http://rest.blueoxen.net/cgi-bin/wiki.pl?QueryStringsConsideredHarmful