API REST Thực tiễn tốt nhất: Đặt tham số ở đâu? [đóng cửa]

API REST có thể có các tham số theo ít nhất hai cách:

1. Là một phần của đường dẫn URL (nghĩa là /api/resource/parametervalue )
2. Là một đối số truy vấn (nghĩa là /api/resource?parameter=value )

Thực hành tốt nhất ở đây là gì? Có hướng dẫn chung nào khi sử dụng 1 và khi nào nên sử dụng 2 không?

Ví dụ trong thế giới thực: Twitter sử dụng các tham số truy vấn để chỉ định các khoảng thời gian. ( http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

Nó có được coi là thiết kế tốt hơn để đặt các tham số này trong đường dẫn URL không?

Nếu có tài liệu thực hành tốt nhất, tôi chưa tìm thấy chúng. Tuy nhiên, đây là một vài hướng dẫn tôi sử dụng khi xác định vị trí đặt tham số trong url:

Các tham số tùy chọn có xu hướng dễ dàng hơn để đặt trong chuỗi truy vấn.

Nếu bạn muốn trả về lỗi 404 khi giá trị tham số không tương ứng với tài nguyên hiện có thì tôi sẽ hướng đến tham số phân đoạn đường dẫn. ví dụ: /customer/232trong đó 232 không phải là id khách hàng hợp lệ.

Tuy nhiên, nếu bạn muốn trả về một danh sách trống thì khi không tìm thấy tham số thì tôi khuyên bạn nên sử dụng tham số chuỗi truy vấn. ví dụ/contacts?name=dave

Nếu một tham số ảnh hưởng đến toàn bộ cây con của không gian URI của bạn thì hãy sử dụng một đoạn đường dẫn. ví dụ: một tham số ngôn ngữ /en/document/foo.txt so với/document/foo.txt?language=en

Tôi thích các định danh duy nhất nằm trong một đoạn đường dẫn hơn là một tham số truy vấn.

Các quy tắc chính thức cho URI được tìm thấy trong thông số RFC này tại đây . Ngoài ra còn có một thông số RFC rất hữu ích khác ở đây xác định các quy tắc để tham số hóa các URI.

Trả lời muộn nhưng tôi sẽ thêm một số thông tin chi tiết bổ sung cho những gì đã được chia sẻ, cụ thể là có một số loại "tham số" cho một yêu cầu và bạn nên tính đến điều này.

1. Trình định vị - Ví dụ: các định danh tài nguyên như ID hoặc hành động / chế độ xem
2. Bộ lọc - Ví dụ: các tham số cung cấp tìm kiếm, sắp xếp hoặc thu hẹp tập kết quả.
3. Trạng thái - Ví dụ: nhận dạng phiên, khóa api, whatevs.
4. Nội dung - Ví dụ dữ liệu sẽ được lưu trữ.

Bây giờ hãy xem xét các vị trí khác nhau nơi các tham số này có thể đi.

1. Yêu cầu tiêu đề & cookie
2. Chuỗi truy vấn URL (vars "GET")
3. Đường dẫn URL
4. Chuỗi truy vấn cơ thể / nhiều phần (vars "POST")

Nói chung, bạn muốn Trạng thái được đặt trong tiêu đề hoặc cookie, tùy thuộc vào loại thông tin trạng thái. Tôi nghĩ rằng tất cả chúng ta có thể đồng ý về điều này. Sử dụng các tiêu đề http tùy chỉnh (X-My-Header) nếu bạn cần.

Tương tự, Nội dung chỉ có một nơi thuộc về, trong phần thân yêu cầu, dưới dạng chuỗi truy vấn hoặc dưới dạng http nhiều phần và / hoặc nội dung JSON. Điều này phù hợp với những gì bạn nhận được từ máy chủ khi nó gửi cho bạn nội dung. Vì vậy, bạn không nên thô lỗ và làm điều đó khác đi.

Các bộ định vị như "id = 5" hoặc "action = refresh" hoặc "page = 2" sẽ có ý nghĩa như một đường dẫn URL, chẳng hạn như mysite.com/article/5/page=2một phần bạn biết mỗi phần nghĩa là gì (những điều cơ bản như bài viết và 5 rõ ràng có nghĩa là lấy cho tôi dữ liệu của loại bài viết có id 5) và các tham số bổ sung được chỉ định là một phần của URI. Chúng có thể ở dạng page=2hoặc page/2nếu bạn biết rằng sau một điểm nhất định trong URI, "thư mục" được ghép các giá trị khóa.

Các bộ lọc luôn đi trong chuỗi truy vấn, bởi vì mặc dù chúng là một phần của việc tìm kiếm dữ liệu phù hợp, nhưng chúng chỉ ở đó để trả về một tập hợp con hoặc sửa đổi những gì Bộ định vị trả về một mình. Tìm kiếm trong mysite.com/article/?query=Obama(tập hợp con) là một bộ lọc và /article/5?order=backwards(sửa đổi) cũng vậy. Hãy suy nghĩ về những gì nó làm, không chỉ những gì nó được gọi là!

Nếu "view" xác định định dạng đầu ra, thì đó là bộ lọc ( mysite.com/article/5?view=pdf) bởi vì nó trả về một sửa đổi của tài nguyên được tìm thấy thay vì tìm kiếm tài nguyên mà chúng ta muốn. Nếu nó thay vì quyết định phần cụ thể nào của bài viết chúng ta sẽ thấy ( mysite.com/article/5/view=summary) thì đó là một công cụ định vị.

Hãy nhớ rằng, thu hẹp một tập hợp các tài nguyên là lọc. Định vị một cái gì đó cụ thể trong một tài nguyên là định vị ... duh. Lọc tập hợp con có thể trả về bất kỳ số lượng kết quả nào (thậm chí 0). Định vị sẽ luôn tìm thấy trường hợp cụ thể của một cái gì đó (nếu nó tồn tại). Lọc sửa đổi sẽ trả về cùng một dữ liệu như trình định vị, ngoại trừ sửa đổi (nếu cho phép sửa đổi như vậy).

Hy vọng điều này sẽ giúp mọi người có những khoảnh khắc eureka nếu họ bị lạc về nơi để đặt đồ đạc!

Nó phụ thuộc vào một thiết kế. Không có quy tắc nào cho các URI tại REST trên HTTP (điều chính là chúng là duy nhất). Thông thường nói đến vấn đề của hương vị và trực giác ...

Tôi thực hiện theo cách tiếp cận sau:

• url path-Element: Tài nguyên và thành phần đường dẫn của nó tạo thành một thư mục truyền tải và một nguồn con (ví dụ / items / {id}, / users / items). Khi không chắc chắn hãy hỏi đồng nghiệp của bạn, nếu họ nghĩ rằng đi ngang và họ nghĩ trong "thư mục khác" thì phần tử đường dẫn rất có thể là lựa chọn đúng
• tham số url: khi thực sự không có truyền tải (tài nguyên tìm kiếm có nhiều tham số truy vấn là một ví dụ rất hay cho điều đó)

IMO các tham số nên tốt hơn như các đối số truy vấn. Url được sử dụng để xác định tài nguyên, trong khi các tham số truy vấn được thêm vào để chỉ định phần nào của tài nguyên bạn muốn, bất kỳ trạng thái nào mà tài nguyên nên có, v.v.

Theo triển khai REST,

1) Biến đường dẫn được sử dụng cho hành động trực tiếp trên tài nguyên, như liên hệ hoặc bài hát cũ ..
GET etc / api / resource / {songid} hoặc
GET etc / api / resource / {contactid} sẽ trả về dữ liệu tương ứng.

2) Perms / argument truy vấn được sử dụng cho các tài nguyên trực tiếp như siêu dữ liệu của một bài hát, .. GET / api / resource / {songid}? Metadata = thể loại sẽ trả về dữ liệu thể loại cho bài hát cụ thể đó.

"Đóng gói" và POST dữ liệu của bạn dựa trên "bối cảnh" mà công cụ định vị tài nguyên vũ trụ cung cấp, có nghĩa là số 1 vì lợi ích của công cụ định vị.

Lưu ý những hạn chế với # 2. Tôi thích POST hơn # 1.

lưu ý: những hạn chế được thảo luận cho

POST trong Có kích thước tối đa cho nội dung tham số POST không?

NHẬN trong Có giới hạn về độ dài của yêu cầu GET không? và Kích thước tối đa của các tham số URL trong _GET

ps các giới hạn này dựa trên khả năng của máy khách (trình duyệt) và máy chủ (cấu hình).

Theo tiêu chuẩn URI , đường dẫn dành cho các tham số phân cấp và truy vấn dành cho các tham số không phân cấp. Tất nhiên nó có thể rất chủ quan những gì được phân cấp cho bạn.

Trong các tình huống có nhiều URI được gán cho cùng một tài nguyên, tôi muốn đặt các tham số - cần thiết để nhận dạng - vào đường dẫn và các tham số - cần thiết để xây dựng biểu diễn - vào truy vấn. (Đối với tôi cách này dễ dàng hơn để định tuyến.)

Ví dụ:

• /users/123 và /users/123?fields="name, age"
• /users và /users?name="John"&age=30

Đối với bản đồ thu nhỏ, tôi thích sử dụng các phương pháp sau:

• /users?name="John"&age=30
• /users/name:John/age:30

Vì vậy, nó thực sự phụ thuộc vào bạn (và bộ định tuyến phía máy chủ của bạn) cách bạn xây dựng các URI của mình.

lưu ý: Chỉ cần đề cập đến các tham số này là tham số truy vấn. Vì vậy, những gì bạn đang thực sự làm là xác định một ngôn ngữ truy vấn đơn giản. Bằng các truy vấn phức tạp (chứa các toán tử như và, hoặc, lớn hơn, v.v.) Tôi khuyên bạn nên sử dụng ngôn ngữ truy vấn đã tồn tại. Khả năng của các mẫu URI rất hạn chế ...

Là một lập trình viên thường ở cuối máy khách, tôi thích đối số truy vấn. Ngoài ra, đối với tôi, nó tách đường dẫn URL khỏi các tham số, thêm rõ ràng và cung cấp nhiều khả năng mở rộng hơn. Nó cũng cho phép tôi có logic riêng giữa tòa nhà URL / URI và trình tạo tham số.

Tôi thực sự thích những gì manuel aldana nói về lựa chọn khác nếu có một số loại cây liên quan. Tôi có thể thấy các bộ phận dành riêng cho người dùng đang thực hiện như vậy.

Không có quy tắc cứng và nhanh, nhưng quy tắc ngón tay cái theo quan điểm thuần túy về khái niệm mà tôi muốn sử dụng có thể được tóm tắt ngắn gọn như thế này: một đường dẫn URI (theo định nghĩa) đại diện cho một tài nguyên và các tham số truy vấn về cơ bản là các sửa đổi trên tài nguyên đó . Cho đến nay mà khả năng không giúp đỡ ... Với một REST API bạn có phương pháp chủ yếu của hành động dựa trên một nguồn duy nhất sử dụng GET, PUTvà DELETE. Do đó, liệu một cái gì đó nên được biểu diễn trong đường dẫn hoặc như một tham số có thể được giảm xuống thành liệu các phương thức đó có ý nghĩa cho biểu diễn trong câu hỏi hay không. Bạn có hợp lý PUTmột cái gì đó ở con đường đó và nó sẽ là âm thanh để làm như vậy? Tất nhiên bạn có thểPUT một cái gì đó ở bất cứ đâu và uốn cong back-end để xử lý nó, nhưng bạn nênPUTing số tiền cho một đại diện của tài nguyên thực tế và không phải là một phiên bản bối cảnh không cần thiết của nó. Đối với các bộ sưu tập tương tự có thể được thực hiện với POST. Nếu bạn muốn thêm vào một bộ sưu tập cụ thể thì URL nào sẽ POSThợp lý.

Điều này vẫn để lại một số khu vực màu xám vì một số đường dẫn có thể chỉ ra số tiền cho trẻ em của tài nguyên phụ huynh có phần tùy ý và phụ thuộc vào việc sử dụng chúng. Một dòng cứng mà điều này rút ra là bất kỳ loại biểu diễn bắc cầu nào cũng phải được thực hiện bằng cách sử dụng tham số truy vấn, vì nó sẽ không có tài nguyên cơ bản.

Để trả lời cho ví dụ trong thế giới thực được đưa ra trong câu hỏi ban đầu (API của Twitter), các tham số thể hiện một truy vấn bắc cầu lọc theo trạng thái của tài nguyên (chứ không phải là phân cấp). Trong ví dụ cụ thể đó, việc thêm vào bộ sưu tập được thể hiện bởi các ràng buộc đó là hoàn toàn không hợp lý và hơn nữa truy vấn đó sẽ không thể được biểu diễn dưới dạng một đường dẫn có ý nghĩa trong các điều khoản của biểu đồ đối tượng.

Việc áp dụng loại phối cảnh hướng tài nguyên này có thể dễ dàng ánh xạ trực tiếp vào biểu đồ đối tượng của mô hình miền của bạn và đưa logic của API đến điểm mà mọi thứ hoạt động rất rõ ràng và theo cách khá tự ghi lại khi nó rõ ràng. Khái niệm này cũng có thể được làm rõ hơn bằng cách bước ra khỏi các hệ thống sử dụng định tuyến URL truyền thống được ánh xạ tới một mô hình dữ liệu không phù hợp thông thường (ví dụ RDBMS). Apache Sling chắc chắn sẽ là một nơi tốt để bắt đầu. Khái niệm về công văn truyền tải đối tượng trong một hệ thống như Zope cũng cung cấp một sự tương tự rõ ràng hơn.

Đây là ý kiến ​​của tôi.

Các tham số truy vấn được sử dụng làm dữ liệu meta cho một yêu cầu. Chúng hoạt động như bộ lọc hoặc sửa đổi cho một cuộc gọi tài nguyên hiện có.

Thí dụ:

/calendar/2014-08-08/events

nên đưa ra các sự kiện lịch cho ngày hôm đó.

Nếu bạn muốn các sự kiện cho một thể loại cụ thể

/calendar/2014-08-08/events?category=appointments

hoặc nếu bạn cần các sự kiện dài hơn 30 phút

/calendar/2014-08-08/events?duration=30

Một thử nghiệm litmus sẽ là để kiểm tra xem yêu cầu vẫn có thể được phục vụ mà không có thông số truy vấn hay không.

Tôi thường hướng tới # 2, Là một đối số truy vấn (ví dụ / api / resource? Tham số = value).

Tùy chọn thứ ba là thực sự đăng tham số = value trong phần thân.

Điều này là do nó hoạt động tốt hơn cho các tài nguyên đa tham số và có thể mở rộng hơn để sử dụng trong tương lai.

Cho dù bạn chọn loại nào, hãy đảm bảo bạn chỉ chọn một, không trộn và kết hợp. Điều đó dẫn đến một API khó hiểu.

Một "chiều" của chủ đề này đã bị bỏ qua nhưng điều đó rất quan trọng: có những lúc "các thực tiễn tốt nhất" phải tuân theo các quy tắc mà chúng tôi đang triển khai hoặc tăng cường với các khả năng REST.

Ví dụ thực tế:

Nhiều ứng dụng web hiện nay thực hiện kiến ​​trúc MVC (Model, View, Controller). Họ cho rằng một đường dẫn tiêu chuẩn nhất định được cung cấp, thậm chí còn nhiều hơn khi các ứng dụng web đó đi kèm với tùy chọn "Bật URL SEO".

Chỉ cần đề cập đến một ứng dụng web khá nổi tiếng: một cửa hàng thương mại điện tử OpenCart. Khi quản trị viên kích hoạt "URL SEO", họ hy vọng các URL đã nói sẽ có định dạng MVC khá chuẩn như:

http://www.domain.tld/special-offers/list-all?limit=25

Ở đâu

• special-offers là bộ điều khiển MVC sẽ xử lý URL (hiển thị trang ưu đãi đặc biệt)

• list-alllà hành động hoặc tên hàm của bộ điều khiển để gọi. (*)

• giới hạn = 25 là một tùy chọn, cho biết 25 mục sẽ được hiển thị trên mỗi trang.

(*) list-alllà một tên hàm hư cấu mà tôi đã sử dụng cho rõ ràng. Trong thực tế, OpenCart và hầu hết các khung MVC đều có chức năng mặc định, ngụ ý (và thường được bỏ qua trong URL) indexđược gọi khi người dùng muốn thực hiện một hành động mặc định. Vì vậy, URL thế giới thực sẽ là:

http://www.domain.tld/special-offers?limit=25

Với một ứng dụng hoặc cấu trúc khung hiện tại khá chuẩn tương tự như trên, bạn sẽ thường nhận được một máy chủ web được tối ưu hóa cho nó, viết lại URL cho nó ("URL không SEO" thực sự sẽ là: http://www.domain.tld/index.php?route=special-offers/list-all&limit=25 :).

Do đó, bạn, với tư cách là nhà phát triển, phải đối mặt với việc xử lý cơ sở hạ tầng hiện có và điều chỉnh "thực tiễn tốt nhất" của bạn, trừ khi bạn là quản trị viên hệ thống, biết chính xác cách điều chỉnh cấu hình viết lại Apache / NGinx (sau này có thể khó chịu!) Và vì vậy trên.

Vì vậy, API REST của bạn thường sẽ tốt hơn nhiều theo các tiêu chuẩn của ứng dụng web giới thiệu, cả về tính nhất quán với nó và tính dễ dàng / tốc độ (và do đó tiết kiệm ngân sách).

Để quay lại ví dụ thực tế ở trên, API REST nhất quán sẽ là một cái gì đó có URL như:

http://www.domain.tld/api/special-offers-list?from=15&limit=25

hoặc (URL không SEO)

http://www.domain.tld/index.php?route=api/special-offers-list?from=15&limit=25

với sự kết hợp của các đối số "đường dẫn được hình thành" và đối số "hình thành truy vấn".

Tôi thấy rất nhiều API REST không xử lý tốt các tham số. Một ví dụ xuất hiện thường xuyên là khi URI bao gồm thông tin nhận dạng cá nhân.

http://software.danielwatrous.com/design-principles-for-rest-apis/

Tôi nghĩ rằng một câu hỏi tất yếu là khi một tham số hoàn toàn không nên là một tham số, mà thay vào đó nên được chuyển đến TIÊU ĐỀ hoặc CƠ THỂ của yêu cầu.

Đó là một câu hỏi rất thú vị.

Bạn có thể sử dụng cả hai, không có bất kỳ quy tắc nghiêm ngặt nào về chủ đề này, nhưng sử dụng các biến đường dẫn URI có một số lợi thế:

• Bộ nhớ cache : Hầu hết các dịch vụ bộ đệm web trên internet không lưu bộ đệm yêu cầu NHẬN khi chúng chứa các tham số truy vấn. Họ làm điều đó bởi vì có rất nhiều hệ thống RPC sử dụng các yêu cầu GET để thay đổi dữ liệu trong máy chủ (thất bại !! Nhận phải là một phương pháp an toàn)

Nhưng nếu bạn sử dụng các biến đường dẫn, tất cả các dịch vụ này có thể lưu trữ các yêu cầu GET của bạn.

• Phân cấp : Các biến đường dẫn có thể biểu thị phân cấp: / Thành phố / Đường / Địa điểm

Nó cung cấp cho người dùng nhiều thông tin hơn về cấu trúc của dữ liệu.

Nhưng nếu dữ liệu của bạn không có bất kỳ mối quan hệ phân cấp nào, bạn vẫn có thể sử dụng các biến Đường dẫn, sử dụng dấu phẩy hoặc dấu chấm phẩy:

/ Thành phố / kinh độ, vĩ độ

Theo quy tắc, sử dụng dấu phẩy khi thứ tự của các tham số có vấn đề, sử dụng dấu chấm phẩy khi thứ tự không quan trọng:

/ IconGenerator / đỏ; xanh dương, xanh lá cây

Ngoài những lý do đó, có một số trường hợp khi sử dụng biến chuỗi truy vấn rất phổ biến:

• Khi bạn cần trình duyệt tự động đặt các biến dạng HTML vào URI
• Khi bạn đang làm việc với thuật toán. Ví dụ: công cụ google sử dụng chuỗi truy vấn:

http: // www.google.com.vn/search?q=rest

Tóm lại, không có bất kỳ lý do mạnh mẽ nào để sử dụng một trong các phương pháp này mà bất cứ khi nào bạn có thể, hãy sử dụng các biến URI.