농장, 사료회사, 검증기관을 API로 연결하자고 하면 가장 먼저 “어떤 엔드포인트를 만들 것인가”를 논의하기 쉽습니다. 하지만 기술적으로 연결되는 것과 같은 사실을 같은 의미로 이해하는 것은 다릅니다. 농장의 feed_amount가 실제 급여량인지 구매량인지, 사료회사의 batch_id가 생산 로트인지 납품 단위인지, 검증기관의 approved가 데이터 수신인지 감축량 검증 완료인지 다르면 API는 오류를 빠르게 전파하는 통로가 됩니다.

탄소 데이터 API는 단순한 시스템 연동이 아닙니다. 누가 어떤 근거를 제출했고, 어느 계산이 그 근거를 사용했으며, 누가 어떤 기준으로 판정했는지를 교환하는 디지털 계약입니다. 먼저 업무 의미와 책임을 정의하고 그다음 URL과 JSON을 설계해야 합니다.

오해: 모든 원자료를 한 데이터베이스에 모으면 검증이 쉬워진다

중앙집중은 검색을 쉽게 만들 수 있지만 권리와 책임까지 해결하지는 않습니다. 농장은 작업일지와 센서 원자료를 보유하고, 사료회사는 제품 사양과 배치 정보를 관리하며, 검증기관은 독립적 판단과 증거를 보관합니다. 각 주체가 책임지는 원본을 무조건 한곳에 복제하면 최신본, 정정 권한, 영업비밀, 보존기간이 모호해집니다.

검증기관에 모든 시스템의 쓰기 권한을 주는 것도 독립성을 해칠 수 있습니다. 검증자는 제출자료를 확인하고 질의·판정·보완요청을 남겨야 하지만 농장의 원자료나 사료 배치를 수정해서는 안 됩니다. API는 데이터를 합치는 것보다 원본의 소유 주체와 읽기·제출·판정 권한을 분명히 하는 방향으로 설계해야 합니다.

또한 API가 있다고 상호운용성이 생기는 것은 아닙니다. 필드명, 단위, 시간대, 식별자, 상태 전이, 오류 처리와 버전 정책까지 일치해야 합니다. OpenAPI 명세는 사람이든 컴퓨터든 소스코드를 보지 않고 HTTP API의 기능을 이해할 수 있게 하는 언어 중립적 인터페이스 설명을 제공합니다. 그러나 도메인의 탄소 의미는 조직이 별도로 합의해야 합니다.

첫 단계는 이해관계자별 원본과 사건을 나누는 것이다

농장의 원본에는 축사·센서·개체 또는 군집 식별, 사육 두수, 급이·환기·청소·이동 사건, 측정값, 교정과 장치 상태가 있습니다. 사료회사의 원본에는 제품 코드, 생산 배치, 성분·유효기간, 출고·납품 수량, 사용지침과 변경 이력이 있습니다. 검증기관의 원본에는 검증 범위, 기준, 중요성 판단, 표본, 질의, 발견사항, 판정과 서명 시각이 있습니다.

세 주체가 공유해야 하는 것은 모든 내부자료가 아니라 연결에 필요한 최소 사건입니다. 예를 들어 FeedDelivered, FeedApplied, SensorObserved, CalibrationPerformed, DataExcluded, CalculationExecuted, EvidenceSubmitted, FindingRaised, StatementVerified처럼 업무 사건을 정의할 수 있습니다. 이름은 구현에 맞게 달라질 수 있지만 ‘사료가 납품됨’과 ‘가축에게 실제 급여됨’을 하나로 합치면 안 됩니다.

GS1 EPCIS는 공급망 사건을 공통 언어로 공유하는 가시성 이벤트 표준입니다. 의무 채택 대상은 아니지만 제품·위치·시간·업무 단계를 분리하는 참고 모델로 쓸 수 있습니다.

공통 데이터 계약에 반드시 들어갈 항목

첫째는 안정적인 식별자입니다. 조직, 농장, 축사, 장치, 센서, 사료제품, 배치, 납품, 적용 프로그램, 검증업무에 서로 다른 ID를 부여합니다. 표시명은 바뀔 수 있으므로 키로 쓰지 않습니다. 외부 식별자와 내부 ID를 혼동하지 않고 발급기관과 네임스페이스를 기록합니다.

둘째는 값과 단위입니다. 12.3만 보내지 말고 값, 단위, 측정원리, 검출한계, 품질 상태를 함께 보냅니다. ppm 농도와 kg CH₄ 배출량은 다른 개념이므로 필드와 스키마를 구분합니다. 단위 변환은 원본을 덮어쓰지 않고 사용한 변환식과 버전을 남깁니다.

셋째는 시간과 유효기간입니다. 관측 시각, 사건 발생 시각, 시스템 수신 시각, 정정 시각을 구분합니다. RFC 3339와 같이 UTC 오프셋이 포함된 형식을 사용하고, 기간은 시작·종료와 경계 포함 규칙을 명시합니다. 사료 적용기간과 검증대상 기간이 다를 수 있으므로 하나의 날짜 필드로 축약하지 않습니다.

넷째는 상태와 상태 전이입니다. draft, submitted, accepted, questioned, superseded, verified, rejected가 무엇을 뜻하고 누가 바꿀 수 있는지 정합니다. accepted는 형식검사 통과일 뿐 내용 검증 완료가 아닐 수 있습니다. 각 상태의 책임과 다음 허용 동작을 문서화합니다.

다섯째는 계보입니다. W3C PROV-O는 데이터의 Entity, 이를 사용·생성한 Activity, 책임 주체인 Agent와 그 관계를 표현하는 기반을 제공합니다. 구현이 RDF일 필요는 없지만 derived_from, generated_by, attributed_to, method_version, source_hash 같은 관계를 일관되게 남길 수 있습니다. 해시에는 알고리즘과 해시 대상이 원문 바이트인지 정규화된 레코드인지도 명시해야 재현할 수 있습니다. 최종 감축량에서 원자료와 계산 실행으로 역추적할 수 있어야 합니다.

여섯째는 정정 방식입니다. 제출된 원자료를 제자리에서 수정하면 검증자가 본 버전이 사라집니다. 오류가 있으면 새 버전을 만들고 이전 버전을 superseded로 연결하며 정정 사유와 승인자를 기록합니다. 삭제 요청과 법적 보존 요구가 충돌할 수 있으므로 데이터 유형별 보존·비식별·접근차단 정책을 별도로 정합니다.

현장 시나리오: 사료 2톤이 감축활동 2톤은 아니다

사료회사가 저메탄 사료 2톤의 납품 이벤트를 보냈다고 가정하겠습니다. 농장 시스템은 입고를 확인했지만 실제 급여기록은 1.7톤이고, 0.2톤은 재고, 0.1톤은 폐기됐습니다. API가 납품량을 적용량으로 취급하면 감축활동이 과대 기록됩니다. 검증기관은 납품서, 재고, 급여일지와 대상 두수의 관계를 질의해야 합니다.

올바른 모델에서는 FeedDelivered와 FeedApplied가 별도 사건이며 같은 배치 ID로 연결됩니다. 적용 사건에는 기간, 축사 또는 대상군, 수량, 단위, 기록방법, 작성자와 증빙 링크가 들어갑니다. 검증기관은 원본을 수정하지 않고 FindingRaised를 생성해 0.3톤 차이에 대한 설명을 요청합니다. 농장은 재고·폐기 사건을 추가하고 제출 묶음의 새 버전을 만듭니다.

이후 계산 서비스는 승인된 적용량, 측정기간, 방법 버전을 사용해 결과를 생성합니다. 검증 판정은 결과값만이 아니라 사용된 증거 묶음과 계산 실행 ID를 참조합니다. 이렇게 해야 나중에 사료 배치 정보가 정정되거나 계산식이 바뀌었을 때 영향을 받은 결과와 보고서를 찾을 수 있습니다.

인증·권한은 파트너 유형보다 행위에 맞춘다

2025년 발행된 RFC 9700은 OAuth 2.0의 최신 보안 모범사례로 토큰 재생 공격에 대한 관련 완화책과 권한·대상 범위 제한 설계를 다룹니다. 서버 간 연동에서는 조직과 워크로드 신원을 분리하고 위험도와 서비스 구조에 맞춰 토큰 수명과 키 회전 정책을 정합니다.

권한은 ‘사료회사 사용자’처럼 넓은 역할 하나로 끝내지 않습니다. farm:A/read:aggregates, farm:A/write:delivery, verification:case-123/read:evidence처럼 대상과 행위를 제한합니다. 대량 다운로드, 원자료 접근, 정정, 검증 판정은 더 높은 권한과 감사 대상으로 둡니다. 농장 동의나 계약 종료 시 토큰만 끊는 것이 아니라 기존 복제본의 사용·보존 권한도 처리해야 합니다.

재시도·오류·버전이 운영 신뢰를 결정한다

농장 네트워크는 자주 끊길 수 있으므로 재시도는 기본 동작입니다. 같은 납품이나 관측이 여러 번 등록되지 않도록 이벤트 ID와 멱등 키를 사용합니다. 서버는 처리 결과를 명확히 반환하고, 성공 응답을 잃어 다시 보낸 요청도 같은 결과로 처리해야 합니다. 대량 업로드는 묶음 ID, 항목별 성공·실패, 재개 지점을 제공합니다.

오류는 형식, 권한, 중복, 참조 ID 없음, 스키마 만료와 검토 보류를 구분하고 재시도 가능 여부와 추적용 상관관계 ID를 제공합니다. completed, rejected 같은 상태값은 예시이며, 실제 API 명세에는 허용 상태와 전이 조건을 표로 고정해야 합니다.

버전은 URL 숫자만의 문제가 아닙니다. 필드·열거값·단위 변경의 호환 정책을 정하고 OpenAPI 문서를 코드와 함께 관리합니다. 폐기 일정과 대체 방법도 파트너에게 공지합니다.

검증기관을 위한 API는 ‘감사 가능성’을 제공해야 한다

검증은 API 응답이 200이라는 사실을 확인하는 일이 아닙니다. ISO 14064-3은 조직·프로젝트·제품의 온실가스 주장에 대한 검증과 타당성평가 원칙 및 요구사항을 다룹니다. 구체적인 프로그램이 있으면 그 요구사항이 추가됩니다. 따라서 API는 특정 표준 준수를 자동 선언하기보다 검증자가 경계, 기준, 근거, 변경 이력과 중요 오류를 평가할 자료를 제공해야 합니다.

검증용 읽기 화면 또는 내보내기에는 제출 당시 스냅샷, 스키마·방법 버전, 원자료 해시, 제외목록, 질의와 답변, 판정 이력이 포함되어야 합니다. 현재값만 조회하면 과거에 무엇을 검토했는지 재현할 수 없습니다. 대규모 원자료는 서명된 URL 또는 시간 제한 접근 URL이나 별도 데이터 패키지로 제공하되 접근과 다운로드를 기록합니다.

실행 체크리스트

  • 농장·사료회사·검증기관이 각각 책임지는 원본과 공유 사건을 정의했는가.

  • 납품, 입고, 실제 급여, 재고, 폐기를 서로 다른 사건으로 구분했는가.

  • 조직·농장·축사·장치·사료 배치·검증업무에 안정적인 ID가 있는가.

  • 값마다 단위, 시각, 품질 상태, 측정·계산 방법 버전을 제공하는가.

  • 제출, 형식수락, 내용검토, 검증완료 상태를 구분하는가.

  • 정정이 원본 덮어쓰기가 아니라 새 버전과 사유로 남는가.

  • 최종 주장부터 원자료·활동·책임 주체까지 역추적할 수 있는가.

  • 토큰 권한을 농장·기간·데이터 유형·행위별 최소 범위로 제한하는가.

  • 재시도와 대량 업로드가 중복 집계를 만들지 않는가.

  • 오류 코드, 상관관계 ID, 재시도 가능 여부가 명확한가.

  • OpenAPI 명세, 예제, 변경 공지와 소비자 계약 테스트가 있는가.

  • 검증자가 제출 당시 스냅샷과 변경 이력을 읽기 전용으로 확인할 수 있는가.

결론: 좋은 API는 연결보다 책임과 의미를 보존한다

API의 성공은 호출 건수로 판단할 수 없습니다. 납품과 적용, 농도와 배출량, 수신과 검증을 구분하고 각 데이터의 원본 책임자를 보존해야 합니다. 식별자, 단위, 시간, 상태, 계보, 정정과 권한이 합의되지 않으면 빠른 연결은 빠른 혼선을 만듭니다.

따라서 순서는 사건·증거 책임 정의, 데이터 계약, 최소 권한, 재시도·버전 정책, 검증 스냅샷 설계입니다. OpenAPI, OAuth, EPCIS, PROV 같은 표준은 이 계약을 표현하고 교환하는 도구입니다. 특정 표준의 이름이 탄소 주장의 적격성을 자동으로 보장하지는 않습니다. 각 프로그램의 방법론과 검증 기준에 맞춰 API가 Evidence Chain을 끊김 없이 보여 줄 때 시스템 간 연결이 신뢰로 이어집니다.

출처