Lubię to:
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"
Jestem zaniepokojony referencją .
Domena systemowa to platforma, która na wiele sposobów jest zintegrowana ze stronami trzecimi poprzez eksport danych i import różnych formatów (xml, excel). Jest wystarczająco dojrzały, aby umożliwić podmiotom zewnętrznym integrację z naszym systemem za pośrednictwem interfejsu API, a konstrukcja tego interfejsu API powoduje to pytanie.
Mamy obiekt, kampanię, która ma identyfikator, którego można użyć do zidentyfikowania i odzyskania zasobu. Konsumenci naszego interfejsu API mogą mieć własny kod referencyjny do tego, co uważają za kampanię w swojej domenie.
W naszym systemie są inne obiekty z takimi polami referencyjnymi innych firm, jak tego oczekują nasi obecni konsumenci. Jednak martwię się, że nakłada na nas ciężar mapowania i nie wiemy, co to jest referencja (liczba, tekst, json?) I dodaje kolejną mylącą właściwość API dla nowych klientów.
Czy uważa się za niewłaściwą praktykę lub zły projekt zezwalanie na pola identyfikatora referencyjnego innej firmy w definicjach obiektów publicznych dla interfejsu API?
Nie sądzę, że istnieje najlepsza praktyka w tym zakresie. Trzymanie nieprzezroczystości
referenceId
w systemie jest wymagane lub nie w zależności od relacji z klientami zewnętrznymi.Ściśle mówiąc, najprawdopodobniej na systemie nie spoczywa odpowiedzialność za mapowanie między modelem a modelem innej firmy. To jest ich. Po prostu pomagasz im w tworzeniu tego mapowania, trzymając to
referenceId
.Ale znowu, jeśli jest to część umowy między tobą a nimi, musisz zachować swoją część umowy i zapewnić tę nieprzejrzystą własność.
źródło
Referencje stron trzecich są dobrym pomysłem, gdy dane są własnością osoby trzeciej, a Ty jesteś tylko depozytariuszem.
Niezwykle pomocne jest również ustanowienie mechanizmu idempotencji dla zapisów / aktualizacji.
Dlatego w pierwszej części ważne jest zawarcie umowy wokół tego odniesienia. Jeśli jest unikalny, wymusz go przy użyciu odpowiedniej logiki i kodów ostrzegawczych / błędów podczas zapisu.
Dla elastyczności typowe jest, że odwołania są ciągami arbitralnymi.
Ponadto zalecam używanie identyfikatorów wewnętrznych, tak jak to zrobiłeś, więc mój model danych nie jest zależny od żadnego konkretnego formatu kluczy.
Wszystkie wewnętrzne odniesienia będą wówczas wykorzystywać wewnętrzny identyfikator. To również lepiej pasuje do świata REST, który może robić takie rzeczy, jak zastosowanie id w linii z adresem URL, patrz następny punkt.
W zewnętrznym interfejsie API zezwalaj na zapytania przy użyciu dowolnego identyfikatora. Możesz to zrobić z osobnym punktem końcowym lub (w świecie REST) za pomocą parametru zapytania.
Re idempotencja, wykorzystując unikalny zewnętrzny identyfikator, można wykryć powtarzające się próby utworzenia rekordu, unikając błędów „podwójnego zapisu”. Dla mnie jest to wyraźny powód, aby nie tylko wspierać tę koncepcję, ale także uczynić ją obowiązkową, jeśli możesz.
W przeciwnym razie możesz użyć identyfikatora transakcji / identyfikatora komunikatu, ale to nie wchodzi w zakres pytania.
źródło