Khái niệm API REST

Tôi có ba câu hỏi về thiết kế API REST mà tôi hy vọng ai đó có thể làm sáng tỏ. Tôi đã tìm kiếm không ngừng trong nhiều giờ nhưng không tìm thấy câu trả lời cho câu hỏi của mình ở bất cứ đâu (có lẽ tôi chỉ không biết tìm kiếm cái gì?).

Câu hỏi 1

Câu hỏi đầu tiên của tôi liên quan đến hành động / RPC. Tôi đã phát triển API REST được một thời gian và tôi đã quen nghĩ về mọi thứ về các bộ sưu tập và tài nguyên. Tuy nhiên, tôi đã gặp một vài trường hợp trong đó mô hình dường như không áp dụng và tôi tự hỏi liệu có cách nào để điều hòa điều này với mô hình REST.

Cụ thể, tôi có một trường hợp sửa đổi tài nguyên khiến email được tạo. Tuy nhiên, tại một thời điểm sau đó, người dùng có thể chỉ ra cụ thể rằng họ muốn gửi lại email đã được gửi trước đó. Khi gửi lại email, không có tài nguyên nào được sửa đổi. Không có trạng thái được thay đổi. Nó chỉ đơn giản là một hành động cần phải xảy ra. Hành động được gắn với loại tài nguyên cụ thể.

Có phù hợp để trộn một số loại cuộc gọi hành động với URI tài nguyên (ví dụ /collection/123?action=resendEmail) không? Sẽ tốt hơn nếu chỉ định hành động và chuyển id tài nguyên cho nó (ví dụ /collection/resendEmail?id=123)? Đây có phải là cách sai để đi về nó? Theo truyền thống (ít nhất là với HTTP), hành động đang được thực hiện là phương thức yêu cầu (GET, POST, PUT, DELETE), nhưng những hành động đó không thực sự cho phép thực hiện các hành động tùy chỉnh với tài nguyên.

Câu hỏi 2

Tôi sử dụng phần chuỗi truy vấn của URL để lọc bộ tài nguyên được trả về khi truy vấn bộ sưu tập (ví dụ /collection?someField=someval). Trong bộ điều khiển API của tôi, sau đó tôi xác định loại so sánh nào sẽ được thực hiện với trường và giá trị đó. Tôi đã tìm thấy điều này thực sự không hoạt động. Tôi cần một cách để cho phép người dùng API chỉ định loại so sánh họ muốn thực hiện.

Ý tưởng tốt nhất mà tôi đã đưa ra cho đến nay là để cho phép người sử dụng API để xác định nó như một phần phụ để tên trường (ví dụ /collection?someField:gte=someval- để cho biết rằng nó phải trả lại tài nguyên, nơi someFieldlớn hơn hoặc bằng (> =) bất cứ điều gì somevallà Đây có phải là một ý tưởng tốt? Một ý tưởng tồi? Nếu vậy, tại sao? Có cách nào tốt hơn để cho phép người dùng chỉ định loại so sánh để thực hiện với trường và giá trị đã cho không?

Câu 3

Tôi thường thấy URI trông giống như /person/123/dogsđể lấy persons dogs. Nói chung, tôi đã tránh một cái gì đó như vậy bởi vì cuối cùng tôi nghĩ rằng bằng cách tạo một URI như thế bạn thực sự chỉ đang truy cập vào một dogsbộ sưu tập được lọc bởi một personID cụ thể . Nó sẽ tương đương với /dogs?person=123. Có bao giờ thực sự là một lý do chính đáng để URI REST sâu hơn hai cấp ( /collection/resource_id) không?

Có phù hợp để trộn một số loại cuộc gọi hành động với URI tài nguyên (ví dụ /collection/123?action=resendEmail) không? Sẽ tốt hơn nếu chỉ định hành động và chuyển id tài nguyên cho nó (ví dụ /collection/resendEmail?id=123)? Đây có phải là cách sai để đi về nó? Theo truyền thống (ít nhất là với HTTP), hành động đang được thực hiện là phương thức yêu cầu (GET, POST, PUT, DELETE), nhưng những hành động đó không thực sự cho phép thực hiện các hành động tùy chỉnh với tài nguyên.

Tôi muốn mô hình hóa nó theo một cách khác, với một bộ tài nguyên đại diện cho các email sẽ được gửi; việc gửi sẽ được xử lý bởi các bên trong của dịch vụ trong khóa học do, tại thời điểm đó, tài nguyên tương ứng sẽ bị xóa. (Hoặc người dùng có thể XÓA tài nguyên sớm, khiến việc hủy yêu cầu thực hiện gửi.)

Dù bạn làm gì, đừng đặt động từ vào tên tài nguyên! Đó là danh từ (và phần truy vấn là tập hợp các tính từ). Động từ kỳ lạ REST!

Tôi sử dụng phần chuỗi truy vấn của URL để lọc bộ tài nguyên được trả về khi truy vấn bộ sưu tập (ví dụ /collection?someField=someval). Trong bộ điều khiển API của tôi, sau đó tôi xác định loại so sánh nào sẽ được thực hiện với trường và giá trị đó. Tôi đã tìm thấy điều này thực sự không hoạt động. Tôi cần một cách để cho phép người dùng API chỉ định loại so sánh họ muốn thực hiện.

Ý tưởng tốt nhất mà tôi đã nghĩ ra cho đến nay là cho phép người dùng API chỉ định nó như một phần phụ cho tên trường (ví dụ /collection?someField:gte=someval- để chỉ ra rằng nó sẽ trả về các tài nguyên trong đó someField lớn hơn hoặc bằng ( >=) bất kể somevallà gì . Đây có phải là một ý tưởng tốt? Một ý tưởng tồi? Nếu vậy, tại sao? Có cách nào tốt hơn để cho phép người dùng chỉ định loại so sánh để thực hiện với trường và giá trị đã cho không?

Tôi muốn chỉ định một mệnh đề bộ lọc chung và lấy đó làm tham số truy vấn tùy chọn cho bất kỳ yêu cầu nào để tìm nạp nội dung của bộ sưu tập. Sau đó, khách hàng có thể chỉ định chính xác cách hạn chế bộ được trả về, theo bất kỳ cách nào bạn muốn. Tôi cũng lo lắng một chút về khả năng khám phá của ngôn ngữ bộ lọc / truy vấn; bạn càng làm cho nó càng phong phú, càng khó cho các khách hàng tùy tiện khám phá. Một cách tiếp cận khác, ít nhất là về mặt lý thuyết, liên quan đến vấn đề có thể khám phá đó là cho phép tạo ra các tài nguyên phụ hạn chế của bộ sưu tập, mà khách hàng có được bằng cách POST một tài liệu mô tả sự hạn chế đối với tài nguyên bộ sưu tập. Nó vẫn là một sự lạm dụng nhẹ, nhưng ít nhất đó là một sự rõ ràng mà bạn có thể khám phá!

Loại khám phá này là một trong những điều mà tôi thấy ít mạnh mẽ nhất với REST.

Tôi thường thấy URI trông giống như /person/123/dogsđể có được những con chó. Nói chung, tôi đã tránh một cái gì đó như vậy bởi vì cuối cùng tôi hình dung rằng bằng cách tạo một URI như thế bạn thực sự chỉ đang truy cập vào bộ sưu tập chó được lọc bởi một ID người cụ thể. Nó sẽ tương đương với /dogs?person=123. Có bao giờ thực sự là một lý do chính đáng để URI REST sâu hơn hai cấp ( /collection/resource_id) không?

Khi bộ sưu tập lồng nhau thực sự là một tính năng phụ của các thực thể thành viên của bộ sưu tập bên ngoài, việc cấu trúc chúng như một tài nguyên phụ là hợp lý. Theo tính năng phụ của Cameron, tôi có nghĩa là một cái gì đó giống như mối quan hệ thành phần UML, trong đó phá hủy tài nguyên bên ngoài một cách tự nhiên có nghĩa là phá hủy bộ sưu tập bên trong.

Các loại bộ sưu tập khác có thể được mô hình hóa như một chuyển hướng HTTP; do đó, /person/123/dogsthực sự có thể được đáp ứng bằng cách thực hiện 307 chuyển hướng đến /dogs?person=123. Trong trường hợp này, bộ sưu tập không thực sự là thành phần UML, mà là tập hợp UML. Sự khác biệt là vấn đề; nó rất quan trọng

Có thể hiểu được một chút bối rối về cách sử dụng REST đúng cách dựa trên tất cả các cách tôi đã thấy các công ty lớn thiết kế API REST của họ.

Bạn đúng ở chỗ REST là một hệ thống thu thập tài nguyên. Nó là viết tắt của Chuyển giao Nhà nước Đại diện. Không phải là một định nghĩa tuyệt vời nếu bạn hỏi tôi. Nhưng các khái niệm chính là 4 ĐỘNG TỪ HTTP và không trạng thái.

Điều quan trọng cần lưu ý là bạn chỉ có 4 ĐỘNG TỪ với REST. Đây là NHẬN, POST, PUT và XÓA. resendVí dụ của bạn sẽ thêm một Động từ mới vào REST. Đây phải là một lá cờ đỏ.

Câu hỏi 1

Điều quan trọng là phải nhận ra rằng người gọi API REST của bạn không cần phải biết rằng việc thực hiện một PUTbộ sưu tập của bạn sẽ dẫn đến một e-mail được tạo. Điều đó có mùi của một rò rỉ với tôi. Những gì họ có thể biết là việc thực hiện PUTcó thể dẫn đến các nhiệm vụ bổ sung mà họ có thể truy vấn sau này. Họ sẽ biết điều này bằng cách thực hiện một GETtài nguyên được tạo gần đây. Điều đó GETsẽ trả về tài nguyên và tất cả các Taskid tài nguyên được liên kết với nó. Sau đó, bạn có thể truy vấn các tác vụ đó để xác định trạng thái của chúng và thậm chí gửi mới Task.

Bạn có một vài lựa chọn.

REST - Cách tiếp cận dựa trên tài nguyên nhiệm vụ

Tạo một taskstài nguyên trong đó bạn có thể gửi các tác vụ cụ thể vào hệ thống của mình để thực hiện các hành động. Sau đó, bạn có thể thực GEThiện tác vụ dựa trên tác vụ được IDtrả về để xác định trạng thái của nó.

Hoặc bạn có thể kết hợp trong SOAP over HTTPDịch vụ web để thêm một số RPC vào kiến ​​trúc của bạn.

truy vấn cho tất cả các nhiệm vụ cho một tài nguyên cụ thể

GET http://server/api/myCollection/123/tasks

{ "tasks" :
    [ { "22333" : "http://server/api/tasks/223333" } ] 
}

ví dụ tài nguyên nhiệm vụ

PUT http://server/api/tasks

{ 
    "type" : "send-email" , 
    "parameters" : 
    { 
         "collection-type" : "foo" , 
         "collection-id" : "123" 
    } 
}

==> trả về id của nhiệm vụ

223334

GET http://server/api/tasks/223334

{ 
    "status" : "complete" , 
    "date" : "whenever" 
}

REST- Sử dụng POST để kích hoạt các hành động

Bạn luôn có thể POSTbổ sung dữ liệu vào tài nguyên. Theo tôi điều này sẽ vi phạm tinh thần của REST nhưng nó vẫn tuân thủ.

Bạn có thể thực hiện một POST tương tự như thế này:

POST http://server/api/collection/123

{ "action" : "send-email" }

Bạn sẽ cập nhật tài nguyên 123 từ bộ sưu tập với dữ liệu bổ sung. Dữ liệu bổ sung đó thực chất là một hành động yêu cầu phụ trợ gửi email cho tài nguyên đó.

Vấn đề tôi gặp phải là vấn đề GETtài nguyên sẽ trả về dữ liệu cập nhật này. Tuy nhiên, điều này sẽ giải quyết các yêu cầu của bạn và vẫn là RESTful.

SOAP - Dịch vụ web chấp nhận tài nguyên thu được từ REST

Tạo một Dịch vụ web mới trong đó bạn có thể gửi e-mail dựa trên ID tài nguyên trước đó từ API REST. Tôi sẽ không đi sâu vào chi tiết về SOAP ở đây vì câu hỏi ban đầu là về REST và hai khái niệm / công nghệ này không nên được so sánh vì đó là Táo và Cam .

Câu hỏi 2

Bạn cũng có một vài lựa chọn ở đây:

Dường như nhiều công ty lớn hơn xuất bản API REST trưng bày searchbộ sưu tập thực sự chỉ là một cách để truyền tham số truy vấn để trả về tài nguyên.

GET http://server/api/search?q="type = myCollection & someField >= someval"

Cái nào sẽ trả về một tập hợp các tài nguyên REST đủ điều kiện, chẳng hạn như:

{
    "results" : 
       { [ 
             "location" : "http://server/api/myCollection/1",
             "location" : "http://server/api/myCollection/9",
             "location" : "http://server/api/myCollection/56"
         ]
       }
}

Hoặc bạn có thể cho phép một cái gì đó như MVEL làm tham số truy vấn.

Câu 3

Tôi thích các cấp phụ hơn là phải quay lại và truy vấn tài nguyên khác bằng một tham số truy vấn. Tôi không tin có bất kỳ quy tắc nào bằng cách này hay cách khác. Bạn có thể thực hiện cả hai cách và cho phép người gọi quyết định cách nào phù hợp hơn dựa trên cách họ lần đầu tiên nhập vào hệ thống.

Ghi chú

Tôi không đồng ý về những bình luận dễ đọc từ người khác. Mặc dù những gì một số người có thể nghĩ rằng REST vẫn không dành cho con người. Đó là cho tiêu thụ máy. Nếu tôi muốn xem Tweets của mình, tôi sử dụng trang web Twitters thường xuyên. Tôi không thực hiện REST GET với API của họ. Nếu tôi muốn lập trình một cái gì đó với các tweet của mình thì tôi sử dụng API REST của họ. Có API nên dễ hiểu, nhưng gtekhông phải là xấu, nó không trực quan.

Điều chính khác với REST là bạn sẽ có thể bắt đầu tại bất kỳ điểm cung cấp nào trong API của mình và điều hướng đến tất cả các tài nguyên được liên kết khác mà KHÔNG biết URL chính xác của các tài nguyên khác trước thời hạn. Kết quả của GETĐỘNG TỪ trong REST sẽ trả về URL REST đầy đủ của các tài nguyên mà nó tham chiếu. Vì vậy, thay vì truy vấn trả về ID của một Personđối tượng, nó sẽ trả về URL đủ điều kiện, chẳng hạn như http://server/api/people/13. Sau đó, bạn luôn có thể điều hướng kết quả theo chương trình ngay cả khi URL thay đổi.

Trả lời bình luận

Trong thế giới thực, thực tế có những thứ cần phải xảy ra mà không tạo, đọc, cập nhật hoặc xóa (CRUD) một tài nguyên.

Các hành động bổ sung có thể được thực hiện trên các tài nguyên. Cơ sở dữ liệu quan hệ điển hình hỗ trợ khái niệm Thủ tục lưu trữ. Đây là các lệnh bổ sung có thể được thực thi trên một tập hợp dữ liệu. REST vốn không có khái niệm đó. Và không có lý do gì nó nên. Các loại hành động này là hoàn hảo cho RPC hoặc SOAP Web Services.

Đây là vấn đề chung tôi thấy với các API REST. Các nhà phát triển không thích các giới hạn về khái niệm bao quanh REST để họ điều chỉnh nó để làm bất cứ điều gì họ muốn. Điều đó phá vỡ nó từ một dịch vụ RESTful mặc dù. Về cơ bản, các URL đó trở thành GETcác lệnh gọi trên các máy chủ giống như REST.

Bạn có một vài lựa chọn:

• Tạo một tài nguyên nhiệm vụ
• Hỗ trợ POSTing dữ liệu bổ sung vào tài nguyên để thực hiện một hành động.
• Thêm các lệnh bổ sung thông qua Dịch vụ web SOAP.

Nếu bạn đã sử dụng một tham số truy vấn mà HTTP VerB bạn sẽ sử dụng để gửi lại email?

• GET- Điều này có gửi lại email VÀ trả lại dữ liệu của tài nguyên không? Điều gì xảy ra nếu một hệ thống lưu trữ URL đó và coi nó như URL duy nhất cho tài nguyên đó. Mỗi lần họ nhấn URL, nó sẽ gửi lại một email.
• POST - Bạn thực sự không gửi bất kỳ dữ liệu mới nào đến tài nguyên, chỉ là một tham số truy vấn bổ sung.

Dựa trên tất cả các yêu cầu đã cho, thực hiện một POSTtài nguyên với action fielddữ liệu POST sẽ giải quyết vấn đề.

Câu hỏi 1: Có phù hợp để trộn một số loại lệnh gọi hành động với URI tài nguyên [hoặc] sẽ tốt hơn nếu chỉ định hành động và chuyển id tài nguyên cho nó?

Câu hỏi hay. Trong trường hợp này, tôi khuyên bạn nên sử dụng cách tiếp cận sau, cụ thể là chỉ định hành động và chuyển ID tài nguyên cho nó. Theo cách này, khi tài nguyên của bạn được sửa đổi lần đầu tiên, nó sẽ gọi /sendEmailhành động (lưu ý phụ: không cần gọi nó là "gửi lại") như một yêu cầu RESTful riêng (mà sau này bạn có thể gọi đi gọi lại, độc lập với tài nguyên được sửa đổi ).

Câu hỏi 2: liên quan đến việc sử dụng một toán tử so sánh như vậy:/collection?someField:gte=someval

Trong khi điều này là kỹ thuật ok, nó có thể là một ý tưởng tồi. Một trong những nguyên tắc chính của REST là khả năng đọc. Tôi đề nghị bạn chỉ cần chuyển toán tử so sánh thành một tham số khác, ví dụ: /collection?someField=someval&operator=gtevà tất nhiên thiết kế API của bạn để nó phục vụ cho trường hợp mặc định (trong trường hợp operatortham số bị loại khỏi URI).

Câu hỏi 3: Có bao giờ thực sự là một lý do chính đáng để URI REST sâu hơn hai cấp độ không?

Yup; cho sự trừu tượng. Ví dụ, tôi đã thấy một vài API REST sử dụng các lớp trừu tượng thông qua nhiều cấp độ URI: /vehicles/cars/123hoặc /vehicles/bikes/123lần lượt cho phép bạn làm việc với thông tin hữu ích liên quan đến cả hai /vehiclesvà /vehicles/bikesbộ sưu tập. Phải nói rằng, tôi không phải là một fan hâm mộ lớn của phương pháp này; bạn sẽ hiếm khi cần làm điều này trong thực tế và rất có thể bạn có thể thiết kế lại API để sử dụng chỉ 2 cấp độ.

Và vâng, như các ý kiến ​​trên cho thấy, trong tương lai, tốt nhất nên chia các câu hỏi của bạn thành các bài đăng riêng biệt;)

Đối với câu hỏi 2, một cách khác có thể linh hoạt hơn: xem xét mỗi tìm kiếm một tài nguyên mà người dùng xây dựng trước khi sử dụng.

giả sử bạn có một thùng chứa "tìm kiếm", ở đó bạn thực hiện POST /api/searches/với đặc tả truy vấn trên nội dung. nó có thể là một JSON, XML hoặc thậm chí là một tài liệu SQL, bất cứ điều gì dễ dàng hơn cho bạn. Nếu truy vấn phân tích chính xác, một tìm kiếm mới được tạo như một tài nguyên mới với URI riêng của nó, giả sử/api/searches/q123/

Sau đó, khách hàng có thể chỉ cần GET /api/searches/q123/lấy kết quả truy vấn.

Cuối cùng, bạn có thể yêu cầu khách hàng xóa truy vấn hoặc xóa nó sau khi đóng phiên.

Có phù hợp để trộn một số loại cuộc gọi hành động với URI tài nguyên không (ví dụ / bộ sưu tập / 123? Action = resendEmail)? Sẽ tốt hơn nếu chỉ định hành động và chuyển id tài nguyên cho nó (ví dụ / bộ sưu tập / resendEmail? Id = 123)? Đây có phải là cách sai để đi về nó? Theo truyền thống (ít nhất là với HTTP), hành động đang được thực hiện là phương thức yêu cầu (GET, POST, PUT, DELETE), nhưng những hành động đó không thực sự cho phép thực hiện các hành động tùy chỉnh với tài nguyên.

Không, nó không phù hợp, vì IRI là để xác định tài nguyên và không hoạt động (tuy nhiên ppl sử dụng phương pháp ghi đè phương thức này trong một thời gian, trong trường hợp khi sử dụng các phương thức POST và GET không được hỗ trợ). Những gì bạn có thể làm là tìm kiếm một phương thức HTTP thích hợp hoặc tạo một phương thức mới. POST có thể là bạn của bạn trong những trường hợp này (ppl sử dụng nó nếu họ không thể tìm thấy một phương thức thích hợp và yêu cầu không được truy xuất). Một cách tiếp cận khác để tạo tài nguyên từ gửi email và do đó POST /emailscó thể gửi thư mà không tạo tài nguyên thực sự. Btw. Cấu trúc URI không mang ngữ nghĩa, do đó, từ góc độ REST, việc bạn sử dụng loại URI nào không thực sự quan trọng. Vấn đề là dữ liệu meta (ví dụ: quan hệ liên kết ) được gán cho các liên kết bạn đã gửi cho khách hàng.

Ý tưởng tốt nhất mà tôi nghĩ ra cho đến nay là cho phép người dùng API chỉ định nó dưới dạng phần phụ của tên trường (ví dụ / bộ sưu tập? SomeField: gte = someval - để chỉ ra rằng nó sẽ trả về tài nguyên trong đó someField lớn hơn hoặc bằng (> =) bất kể someval là gì. Đây có phải là một ý tưởng tốt? Một ý tưởng tồi? Nếu vậy, tại sao? Có cách nào tốt hơn để cho phép người dùng chỉ định loại so sánh để thực hiện với trường và giá trị nhất định không?

Bạn không phải tạo một ngôn ngữ truy vấn riêng. Tôi thà sử dụng một cái đã có sẵn và thêm một số mô tả truy vấn vào siêu dữ liệu liên kết. Bạn có thể sử dụng loại phương tiện RDF (ví dụ JSON-LD) để làm điều đó hoặc sử dụng loại MIME tùy chỉnh (afaik không có định dạng không phải RDF hỗ trợ điều này). Sử dụng các tiêu chuẩn hiện có tách rời máy khách của bạn khỏi máy chủ, đó là những gì ràng buộc về giao diện thống nhất.

Nó sẽ tương đương với / chó? Người = 123. Có bao giờ thực sự là một lý do chính đáng để URI REST sâu hơn hai cấp (/ sưu tập / resource_id) không?

Như tôi đã đề cập trước đây, cấu trúc URI không quan trọng từ góc độ REST. Bạn có thể sử dụng /x71fd823df2ví dụ. Nó vẫn có ý nghĩa với các máy khách vì chúng kiểm tra dữ liệu meta được gán cho các liên kết chứ không phải cấu trúc URI. Mục đích chính của URI là xác định tài nguyên. Trong tiêu chuẩn URI, họ tuyên bố rằng đường dẫn chứa dữ liệu phân cấp và truy vấn chứa dữ liệu không phân cấp. Nhưng nó có thể rất chủ quan những gì được phân cấp. Đó là lý do tại sao bạn gặp nhiều URI và URI sâu với nhiều truy vấn dài.

Tôi đã tìm kiếm không ngừng trong nhiều giờ nhưng không tìm thấy câu trả lời cho câu hỏi của mình ở bất cứ đâu (có lẽ tôi chỉ không biết tìm kiếm cái gì?).

Bạn nên đọc ít nhất các ràng buộc REST từ luận văn Fielding , tiêu chuẩn HTTP và có thể là API web thế hệ thứ 3 từ Markus.