Có phải thực tiễn xấu đối với định nghĩa đối tượng API chứa Id tham chiếu của bên thứ 3 là thuộc tính không?

Như thế này:

Campaign:
type: object
properties:
  id: 
    type: string
    description: "A GUID identifier"
  referenceId:
    type: string
    description: "A consumers identifier they have used to map their own systems logic to this object."
  name:
    type: string
    description: "'Great Campaign 2017' as an example"

Tôi quan tâm đến tài liệu tham khảo .

Miền hệ thống là một nền tảng được tích hợp với các bên thứ 3 theo nhiều cách thông qua xuất và nhập dữ liệu ở các định dạng khác nhau (xml, excel). Nó đủ chín chắn để cho phép các bên thứ 3 tích hợp với hệ thống của chúng tôi thông qua API và thiết kế của API này là điều thúc đẩy câu hỏi này.

Chúng tôi có một đối tượng, một Chiến dịch, có một id có thể được sử dụng để xác định và truy xuất tài nguyên. Người tiêu dùng API của chúng tôi có thể có mã tham chiếu riêng cho những gì họ coi là Chiến dịch trong miền của họ.

Có các đối tượng khác trong hệ thống của chúng tôi với các trường tham chiếu của bên thứ 3 như thế này và nó được mong đợi từ người tiêu dùng hiện tại của chúng tôi. Tuy nhiên, tôi lo lắng rằng nó đặt gánh nặng ánh xạ lên chúng tôi và chúng tôi không biết tài liệu tham khảo này là gì (số, văn bản, json?) Và nó thêm một thuộc tính khó hiểu khác vào API cho người tiêu dùng mới.

Được coi là thực tiễn xấu hoặc thiết kế xấu để cho phép các trường Id tham chiếu của bên thứ 3 trong định nghĩa đối tượng công khai cho API?

Đây không phải là vấn đề; nó là một điều cần thiết Việc thiếu lĩnh vực này sẽ có vấn đề cho việc tích hợp với các hệ thống khách hàng.

Có rất nhiều trường hợp sử dụng phổ biến cho loại điều này. Ví dụ: API liên quan đến thanh toán có khả năng cho phép các công ty chỉ định số hóa đơn của riêng họ, phần mềm quản lý lực lượng lao động cần bạn để có thể nhập ID nhân viên địa phương của riêng bạn, v.v.

Thiết kế đơn giản nhất để tránh bất kỳ mối quan tâm nào chỉ đơn giản là không chịu bất kỳ trách nhiệm nào cho lĩnh vực này. Chỉ cần cung cấp nó và cho phép khách hàng sử dụng nó nếu họ chọn. Không xác thực hoặc sử dụng nó theo logic của riêng bạn, vì làm như vậy (ngay cả với chức năng có vẻ tốt) có thể khiến bạn vướng vào các vấn đề hoặc lỗi thiết kế của chính khách hàng, cũng như tạo ra các yêu cầu cụ thể của nhà cung cấp hoặc yêu cầu tính năng. Chắc chắn không sử dụng giá trị này như một ID trong nội bộ. Cấu trúc dữ liệu bạn đã chỉ ra ngụ ý đây là cách tiếp cận bạn đang thực hiện.

Về mặt định dạng, nó chỉ cần đủ cho phép để cho phép mọi thứ hợp lý, và sau đó bạn không cần phải quan tâm những gì trong đó. Đây là những gì bạn đã làm bằng cách biến nó thành một trường chuỗi.

Đối với tôi, tên tham chiếuID không quá rõ ràng. Tôi có thể gọi nó là một cái gì đó giống như customerLocalID. Nhưng sau đó, một lần nữa, có thể thuật ngữ của bạn có ý nghĩa trong miền của bạn. Trong mọi trường hợp, tôi không thấy vấn đề gì đối với khách hàng mới miễn là lĩnh vực này được ghi lại rõ ràng (đặc biệt nhấn mạnh rằng đó là tùy chọn).

Tôi không nghĩ rằng có một thực tiễn tốt nhất về việc này. Giữ một mờ đục referenceIdtrong hệ thống của bạn là cần thiết hay không tùy thuộc vào mối quan hệ của bạn với các khách hàng bên thứ 3.

Nói một cách chính xác, rất có thể, hệ thống của bạn không phải là trách nhiệm của bản đồ giữa mô hình của bạn và mô hình bên thứ 3. Nó là của họ. Bạn chỉ cần giúp họ thực hiện bản đồ đó bằng cách giữ nó referenceId.

Nhưng một lần nữa, nếu đây là một phần trong hợp đồng của bạn giữa bạn và họ thì bạn phải giữ một phần của món hời và cung cấp tài sản mờ đục đó.

Tài liệu tham khảo của bên thứ 3 là một ý tưởng tốt trong đó bất kỳ dữ liệu cụ thể nào thuộc sở hữu của bên thứ ba và bạn chỉ là người giám sát.

Nó cũng cực kỳ hữu ích để thiết lập một cơ chế cho tính không thay đổi để ghi / cập nhật.

Vì vậy, trong phần đầu tiên, điều quan trọng là thiết lập hợp đồng xung quanh tài liệu tham khảo đó. Nếu nó là duy nhất, thì hãy thực thi nó với logic và cảnh báo / mã lỗi thích hợp khi ghi.

Để linh hoạt, nó là điển hình cho các tham chiếu là các chuỗi tùy ý.

Ngoài ra, tôi cũng khuyên bạn nên sử dụng số nhận dạng nội bộ, như bạn đã làm, vì vậy mô hình dữ liệu của tôi không phụ thuộc vào bất kỳ định dạng cụ thể nào cho các khóa.

Tất cả các tham chiếu nội bộ sau đó sẽ sử dụng định danh nội bộ. Điều này cũng phù hợp hơn với thế giới REST có thể thực hiện những việc như áp dụng id phù hợp với URL, xem điểm tiếp theo.

Trên API bên ngoài, cho phép truy vấn bằng cách sử dụng một trong hai định danh. Bạn có thể làm điều đó với một điểm cuối riêng biệt hoặc (trong thế giới REST) ​​bằng tham số truy vấn.

Tính không ổn định, bằng cách sử dụng một mã định danh bên ngoài duy nhất, có thể phát hiện các nỗ lực lặp lại để tạo một bản ghi, tránh các lỗi "ghi hai lần". Đối với tôi, đó là lý do rõ ràng để không chỉ hỗ trợ khái niệm, mà còn khiến nó bắt buộc, nếu bạn có thể.

Không thể sử dụng id của tin nhắn / id giao dịch hoạt động, nhưng điều đó nằm ngoài phạm vi của câu hỏi.