Bir API nesne tanımının 3. taraf referans kimliklerini özellik olarak içermesi kötü bir uygulama mudur?

Bunun gibi:

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"

ReferenceId hakkında endişeliyim .

Sistem etki alanı, veri dışa aktarma ve çeşitli biçimlerde (xml, excel) içe aktarma yoluyla 3. taraflarla birçok şekilde entegre edilen bir platformdur. Üçüncü tarafların bir API aracılığıyla sistemimizle entegre olmasına izin verecek kadar olgun ve bu API'nın tasarımı bu soruyu harekete geçiriyor.

Kaynağı tanımlamak ve almak için kullanılabilecek bir tanıtıcıya sahip bir nesne, bir Kampanya var. API'mızın tüketicileri, alan adlarında bir Kampanya olarak gördükleri şeye ilişkin kendi referans kodlarına sahip olabilirler.

Sistemimizde üçüncü taraf referans alanları olan başka nesneler de mevcut ve mevcut tüketicilerimizden bekleniyor. Ancak, üzerimize haritalama yükü getiriyor ve bu referansın ne olduğunu bilmiyoruz (sayı, metin, json?) Ve yeni tüketiciler için API'ye başka bir kafa karıştırıcı özellik ekliyor.

Bir API için ortak nesne tanımlarında 3. Taraf referans kimliği alanlarına izin vermek kötü uygulama veya kötü tasarım olarak mı değerlendiriliyor?

Bu sorun değil; bu bir zorunluluktur. Bu alanın eksikliği, müşteri sistemlerine entegrasyon açısından sorunlu olacaktır.

Bu tür şeyler için çok sayıda yaygın kullanım durumu vardır. Örneğin, faturalandırmayı içeren bir API, şirketlerin kendi fatura numaralarını belirlemelerine izin verebilir, işgücü yönetimi yazılımı kendi yerel çalışan kimliklerinizi girebilmenizi gerektirir.

Herhangi bir endişeyi önlemek için en basit tasarım, sadece alan için herhangi bir sorumluluk almamaktır. Sadece sağlayın ve müşterilerin istedikleri takdirde kullanmasına izin verin. Bunu doğrulamayın veya kendi mantığınızda kullanmayın, bunu yapmak (iyi görünen işlevsellikle bile) müşterinin kendi tasarım sorunlarına veya hatalarına karışmanın yanı sıra tedarikçiye özgü beklentiler veya özellik istekleri oluşturabilir. Kesinlikle bu değeri dahili olarak kimlik olarak kullanmayın. Gösterdiğiniz veri yapısı, bu yaklaşımın izlediğiniz yaklaşım olduğunu gösterir.

Biçimler açısından, makul bir şeye izin verecek kadar izin vericidir ve sonra içinde ne olduğunu önemsemeniz gerekmez. Bir dize alanı yaparak bunu yaptık.

Bana göre referenceID adı o kadar net değil. Buna customerLocalID gibi bir şey diyebilirim. Ama sonra tekrar, belki terminolojiniz alanınızda mantıklı geliyor. Her halükarda, alan açıkça belgelendiği sürece yeni müşteriler için bir sorun görmüyorum (özellikle isteğe bağlı olduğunu vurgulamak).

Bununla ilgili en iyi uygulamaların olduğunu düşünmüyorum. referenceId3. taraf istemcilerle olan ilişkinize bağlı olarak sisteminizde bir opak bulundurmanız gerekir.

Açıkçası, büyük olasılıkla, modelinizle 3. taraf modeli arasında eşlemek sisteminizin sorumluluğu değildir. Bu onların. Siz sadece bu haritayı tutmalarına yardım edersiniz referenceId.

Ama yine de, bu, sizinle aranızdaki sözleşmenin bir parçasıysa, pazarlığın bir kısmını tutmalı ve o opak mülkü sağlamalısınız.

3. taraf referansları, belirli verilerin üçüncü tarafa ait olduğu ve sadece bir bakıcı olduğunuzda iyi bir fikirdir.

Yazma / güncelleme için idempotency için bir mekanizma oluşturmak da son derece yararlıdır.

Bu nedenle, ilk bölümde, söz konusu referansın etrafında bir sözleşme yapılması önemlidir. Benzersiz ise, yazma sırasında uygun mantık ve uyarı / hata kodlarıyla uygulayın.

Esneklik için, referansların keyfi dizeler olması tipiktir.

Ayrıca, yaptığınız gibi dahili tanımlayıcıları da kullanmanızı öneririm, bu nedenle veri modelim anahtarlar için belirli bir formata bağımlı değildir.

Tüm dahili referanslar daha sonra dahili tanımlayıcıyı kullanır. Bu aynı zamanda URL ile aynı kimliğe sahip uygulama gibi şeyler yapabilen REST dünyasına daha iyi uyuyor, bir sonraki noktaya bakın.

Harici API'de, tanımlayıcılardan birini kullanan sorgulara izin verin. Bunu ayrı bir uç nokta ile veya (REST dünyasında) bir sorgu parametresi kullanarak yapabilirsiniz.

Eşitsizlik, benzersiz bir harici tanımlayıcı kullanarak, "çift yazma" hatalarından kaçınarak bir kayıt oluşturmak için tekrarlanan girişimleri algılamak mümkündür. Benim için, sadece konsepti desteklemek değil, mümkünse zorunlu kılmak için açık bir sebep budur.

İşlem işlem kimlikleri / ileti kimlikleri kullanabiliyorsanız, ancak bu sorunun kapsamı dışındadır.