Czy złą praktyką jest, aby definicja obiektu API zawierała identyfikatory referencji innych firm jako właściwości?

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?

To nie jest problem; to konieczność. Brak tego pola byłby problematyczny dla integracji z systemami klienta.

Istnieje wiele typowych przypadków użycia tego rodzaju rzeczy. Na przykład interfejs API obejmujący fakturowanie prawdopodobnie pozwoli firmom na określenie własnych numerów faktur, oprogramowanie do zarządzania pracownikami wymaga wprowadzenia własnych lokalnych identyfikatorów pracowników itp.

Najprostszym rozwiązaniem pozwalającym uniknąć jakichkolwiek obaw jest po prostu nie ponoszenie żadnej odpowiedzialności za teren. Po prostu podaj go i pozwól klientom korzystać z niego, jeśli zechcą. Nie sprawdzaj jej poprawności ani nie używaj jej we własnej logice, ponieważ takie postępowanie (nawet przy funkcjonowaniu, które wydaje się dobre) może uwikłać Cię w problemy projektowe lub błędy klienta, a także może powodować oczekiwania i żądania dotyczące konkretnych funkcji. Z pewnością nie używaj tej wartości jako identyfikatora wewnętrznie. Pokazana struktura danych sugeruje, że podchodzisz do tego.

Jeśli chodzi o formaty, musi to być na tyle liberalne, aby pozwolić na coś rozsądnego, a wtedy nie musisz się przejmować tym, co w nim jest. To właśnie zrobiłeś, tworząc z niego ciąg znaków.

Dla mnie nazwa referencyjny nie jest tak jasny. Mogę nazwać to czymś w rodzaju customerLocalID. Ale może twoja terminologia ma sens w twojej dziedzinie. W każdym razie nie widzę problemu dla nowych klientów, dopóki pole jest wyraźnie udokumentowane (szczególnie podkreślając, że jest opcjonalne).

Nie sądzę, że istnieje najlepsza praktyka w tym zakresie. Trzymanie nieprzezroczystości referenceIdw 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ść.

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.