API 객체 정의에 타사 참조 ID를 속성으로 포함시키는 것은 나쁜 습관입니까?

이처럼 :

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가 걱정 됩니다.

시스템 도메인은 다양한 형식 (xml, excel)의 데이터 내보내기 및 가져 오기를 통해 여러 가지 방식으로 타사와 통합 된 플랫폼입니다. API를 통해 타사가 시스템과 통합 할 수있을만큼 충분히 성숙했으며이 API의 디자인이이 질문을 유발합니다.

우리는 자원을 식별하고 검색하는 데 사용할 수있는 id를 가진 Campaign이라는 오브젝트를 가지고 있습니다. Google API 소비자는 도메인 내 캠페인으로 간주하는 것에 대한 자체 참조 코드를 보유 할 수 있습니다.

시스템에 이와 같은 타사 참조 필드가있는 다른 개체가 있으며 기존 소비자로부터 예상됩니다. 그러나 나는 그것이 우리에게 매핑 해야하는 부담을 안고 걱정하고 우리는이 referenceId가 무엇인지 (숫자, 텍스트, json?) 알지 못하고 새로운 소비자를 위해 API에 또 다른 혼란스러운 속성을 추가합니다.

API에 대한 공개 객체 정의에서 타사 참조 ID 필드를 허용하는 것은 나쁜 습관 또는 나쁜 디자인으로 간주됩니까?

이것은 문제가되지 않습니다. 그것은 필수입니다. 이 분야의 부족은 고객 시스템과의 통합에 문제가 될 수 있습니다.

이런 종류의 일반적인 사용 사례가 많이 있습니다. 예를 들어, 청구와 관련된 API는 회사가 자체 송장 번호를 지정하고, 인력 관리 소프트웨어가 자신의 현지 직원 ID를 입력 할 수 있어야합니다.

우려를 피하기위한 가장 간단한 설계는 현장에 대한 책임을지지 않는 것입니다. 제공하고 고객이 원하는 경우 사용하도록하십시오. 이를 검증하거나 자신의 논리에서 사용하지 마십시오. 기능이 우수하더라도 고객 자신의 설계 문제 나 버그에 얽매여 벤더별 기대치 나 기능 요청을 생성 할 수 있기 때문입니다. 물론 내부적으로 ID로이 값을 사용하지 않습니다. 당신이 보여준 데이터 구조는 이것이 당신이 취하는 접근법이라는 것을 암시합니다.

형식의 관점에서, 그것은 합리적인 것을 허용하기에 충분히 관대해야하며, 그 안에 무엇이 있는지 신경 쓰지 않아도됩니다. 이것은 문자열 필드로 만들어서 수행 한 것입니다.

나에게 referenceID라는 이름이 명확하지 않습니다. customerLocalID와 같은 이름으로 부를 수 있습니다. 그러나 다시 말하지만, 귀하의 용어는 귀하의 도메인에서 의미가 있습니다. 어쨌든 필드가 명확하게 문서화되어있는 한 (특히 선택 사항임을 강조 표시하는) 신규 고객에게는 문제가 없습니다.

나는 이것에 관한 모범 사례가 있다고 생각하지 않습니다. referenceId타사 클라이언트와의 관계에 따라 시스템에서 불투명 을 유지해야합니다.

엄밀히 말하면, 아마도 모델과 타사 모델을 매핑하는 것은 시스템의 책임이 아닙니다. 그것은 그들의 것이다. 당신 은 그것을 유지함으로써 그들이 그 매핑을 할 수 있도록 도와줍니다referenceId .

그러나 다시, 이것이 당신과 그들 사이의 계약의 일부라면, 당신은 거래의 일부를 유지하고 그 불투명 한 속성을 제공해야합니다.

제 3 자 참조는 특정 데이터가 제 3자가 소유하는 경우 좋은 아이디어이며 귀하는 단지 관리자입니다.

쓰기 / 업데이트의 dem 등성 메커니즘을 설정하는 것도 매우 도움이됩니다.

따라서 첫 번째 부분에서는 해당 참조에 대한 계약을 설정하는 것이 중요합니다. 고유 한 경우 쓰기시 적절한 논리 및 경고 / 오류 코드로 적용하십시오.

유연성을 위해 참조가 임의의 문자열 인 것이 일반적입니다.

또한, 내부 식별자도 사용하는 것이 좋습니다. 따라서 내 데이터 모델은 키의 특정 형식에 의존하지 않습니다.

그런 다음 모든 내부 참조는 내부 식별자를 사용합니다. 이것은 URL과 일치하여 id를 적용하는 것과 같은 일을 할 수있는 REST 세계에 더 적합합니다. 다음 사항을 참조하십시오.

외부 API에서 두 식별자 중 하나를 사용하여 쿼리를 허용하십시오. 별도의 엔드 포인트 또는 쿼리 매개 변수를 사용하여 (REST 세계에서)이를 수행 할 수 있습니다.

고유 한 외부 식별자를 사용하여 중복성 (redemandency)을 사용하면 "이중 쓰기"오류를 피하면서 레코드를 작성하려는 반복 된 시도를 감지 할 수 있습니다. 저에게는 그것이 컨셉을지지 할뿐만 아니라 가능하다면 의무적으로 만드는 명확한 이유입니다.

작업 트랜잭션 ID / 메시지 ID를 사용할 수 없지만 질문의 범위를 벗어납니다.