Trả lại dữ liệu tổng hợp về tài nguyên

Question

Cho phép nói rằng bạn đang dẫn đầu việc phát triển API REST mới. Greenfield.

Và bạn đã có cấu trúc này cho một người cho REST API của bạn, lược đồ này:

{ 
    "id": 12, 
    "name":{ 
      "first":"Angie", 
      "last": "Smith", 
      "middle": "joy", 
      "maiden": "crowly", 
    }, 
    "address": { 
      "street": "1122 Something St.", 
      ..and so on... 
    }, 
... and so on 
} 

và cho phép nói rằng bạn có một khách hàng của API của bạn (trong trường hợp này một đội web hoàn toàn mới đó là được thuê đó là từ xa và rất thiếu kinh nghiệm) đến với bạn và nói "Này tôi cần một danh sách của tất cả các tên cuối cùng duy nhất trong hệ thống".

có bạn:

a) Nói với người đó "OK, chắc chắn, cũng tên là đã là một phần của thiết bị đầu cuối người tài nguyên của chúng tôi Chúng tôi có thể trở lại chỉ là một danh sách những người mà sẽ cung cấp cho bạn chỉ là cái tên.. lĩnh vực cuối cùng trở lại, và bạn chỉ nhận được một người cho mỗi tên khác nhau.last tồn tại ". Về cơ bản chỉ cần cung cấp cho họ một nhóm tổng hợp của người dân để đáp ứng nhu cầu của họ về cơ bản mỗi tên cuối cùng duy nhất trong cơ sở dữ liệu cho người dân.

như vậy cho giả dụ url họ sẽ chỉ cần gọi /people?fields=name.last?aggregate

b) Oh ok, chúng tôi sẽ chỉ tạo ra một thiết bị đầu cuối đặc biệt cho bạn, chúng tôi không biết điều đó có tài nguyên hoặc thiết bị đầu cuối url sẽ trông như vậy, nhưng chúng tôi sẽ cung cấp cho bạn điều này:

{ 
    "lastNames": { 
      "name": "Anderson", 
      "name": "Alvertson", 
     ....etc. 
     } 
} 

Và ai biết tài nguyên này là gì, không có tên bạn thậm chí có thể cung cấp cho điều này.

và bạn đã quên tất cả các lợi ích của REST vì khách hàng của bạn từ chối hiểu rằng bạn có Kiến trúc và quy ước để duy trì và bạn cung cấp cho họ những gì họ cần thông qua tài nguyên mà bạn thiết lập nhưng họ nghĩ thật kỳ lạ là họ phải tuân thủ sắp xếp mẫu tài nguyên và mong đợi bạn xây dựng các tài nguyên tùy chỉnh vô tận/vô tận mà không có sự nhất quán hoặc không có cách nào để đặt tên cho các tài nguyên này bởi vì chúng kết hợp API của bạn với ứng dụng của chúng và chúng mong đợi bạn tuân theo bất kỳ hợp đồng nào mà bạn cảm thấy nên thiết kế ... nghĩa là họ cảm thấy họ có thể cho bạn biết cách thiết kế API của bạn theo nghĩa đen và bạn không nói gì cả!

Và bạn biết nếu bạn chỉ cung cấp một lần và bỏ qua tài nguyên REST hiện tại của bạn ở đây là "Người" mà họ có thể mong đợi bạn từ bỏ bất kỳ quyết định thiết kế nào bạn đã thực hiện hoặc muốn thực hiện với API kể từ khi bạn đưa vào họ nói rằng họ không quan tâm đến thiết kế của bạn nhưng bạn là nhóm nền tảng tạo API này để tiêu thụ toàn công ty!

Và bạn biết rằng API của bạn có thể được nhiều ứng dụng, dịch vụ khác hoặc thậm chí là công chúng sử dụng trong một ngày.

hoặc

c) chỉ nói e này và bỏ alltogether do sự căng thẳng của liên tục cố gắng để giải thích cho họ nghỉ ngơi và lý do tại sao bạn đang cố gắng để giữ ước nhất định ngay cả những ý tưởng đơn giản các nguồn lực có ý nghĩa và cố gắng sử dụng lại những tài nguyên đó để lấy dữ liệu có liên quan và tìm một nơi và nhóm tốt hơn để làm việc cùng, vì sau khi xây dựng và khéo léo cố gắng nói với họ về thời gian và thời gian một lần nữa, chúng tôi có các quy ước mà chúng tôi đang tuân thủ trên API, nhóm web vẫn cảm thấy họ cần phải ra lệnh cho thiết kế REST API của bạn 100% mà họ không có manh mối về REST và vì vậy họ không quan tâm những gì bạn nói ...họ nghĩ rằng họ chỉ có thể sở hữu API ngay cả khi bạn và nhóm nền tảng xây dựng nó cho công ty không chỉ tiêu thụ mà còn có thể cho các ứng dụng, dịch vụ khác hoặc thậm chí hiển thị API này cho người tiêu dùng công trong tương lai.

Answer 1

Từ kinh nghiệm của tôi, đây là vấn đề phổ biến nhất trong hợp tác giữa REST (hoặc bất kỳ nhà cung cấp API) và web, điện thoại di động, bất kỳ người tiêu dùng API nào.

Tôi luôn cố gắng tuân thủ các quy tắc càng nhiều càng tốt và buộc người tiêu dùng chấp nhận các quy ước và kiến ​​trúc của tôi. Tại sao? Vì lý do bạn đề cập, một trong số đó là rất quan trọng: API của bạn có thể trở thành công khai vào một ngày nào đó và bạn không thể để bản thân giới thiệu điểm cuối mới mỗi lần người tiêu dùng cần hiển thị người dùng bằng váy màu hồng.

Do đó a hợp lý với tôi và trình bày phương pháp RESTful nhất.

b không hợp lý vì những lý do được đề cập ở trên. Hãy nhớ rằng trong loại vấn đề này, khó khăn nhất là giới thiệu điểm cuối chuyên dụng đầu tiên. Khi nó được thực hiện, tiếp theo chỉ là vấn đề thời gian.

Đôi khi c có ý nghĩa rất lớn đối với tôi nhưng tôi vẫn cố gắng giải thích;)

Hãy nhớ rằng khi thiết kế/thực hiện các API bạn phải phù hợp với các quy tắc - ngay cả khi bạn thiết lập các quy tắc của chính mình.