애플리케이션 작업

(섹션: 운영 및 관리)

1) 목적과 원칙

API는 생태계의 "운영 계층" 입니다. 계약을 통해 자동화되지 않은 것은 수동 작업과 위험으로 바뀝니다.

• 계약 우선: 첫 번째 사양 (OpenAPI/JSON Schema/AsyncAPI), 구현.
• 기본값으로 안전: 최소 스코프, 짧은 TTL, 상호 TLS/서명.
• 관찰 가능: 엔드 투 엔드 추적 및 SLA 메트릭.
• Idempotent: 안전한 재생.
• 역으로 호환되는: "파괴" 가없는 진화.
• 청각 가능: 암호로 확인 된 사실 (영수증).

2) 계약 및 모델 (참조)

동기화 요청을위한 OpenAPI; 이벤트/웹 후크를위한 AsyncAPI.
각 리소스에 필요한 필드는 'id', '버전', '생성 된 _ at', '업데이트 된 _ at', '테넌트', '지역', 'trace _ id' 입니다.

계약 조각의 예

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) 인증, 인증, 범위

사용자/파트너를위한 OAuth2/OIDC 클라이언트 자격 증명/JWT 자격 증명 S2S.
스코프/리소스 역할: '지불. ',' 카탈로그를 작성하십시오. ',' 감사를 읽으십시오. 수출 '.
ReBAC: "소유권 별" (테넌트/계정/하위 계정) 액세스.
JIT 비밀: 수명이 짧은 토큰, 장치/서브넷/지역 바인딩.
중요한 작업 (결제, 키) 을위한 장치 자세 및 mTLS.

4) 이념과 "정확히 한 번"

TTL 창에서 '(키, 계정, 경로)' 에 의한 Idempotency-Key (헤더) + dedup.
이벤트를 게시하기위한 전송/CDC-보장 된 전달.
정확히 한 번의 효과: 부작용은 거래 저널을 통해 포착됩니다. 반복은 동일한 "영수증" ('영수증 _ 해시') 으로 이어집니다.
시작 정책: 지수 백오프, 지터, 최대 창.

5) 한계, 할당량, 우선 순위

요율 제한: 키/테넌트/경로/지역; "소프트" (429) 및 "하드" (컷오프).
쿼터/예산: 월별/일일 캡, 웹 후크 'QuotaCapReached'.
공정 사용: 서비스 수준 별 세입자 우선 순위 (골드/실버/브론즈).
버스트 버퍼: 이웃의 열화없이 짧은 버스트.

6) Pagination, 필터, 샘플

커서 기반 (안정적인 순서의 '생성 _ at, id'), '페이지 _ 크기'

로그/트랜잭션을위한 시간 슬라이스 샘플 ('에서', '에서', '워터 마크').

필터링 DSL: 흰색으로 표시된

일관성 힌트: API를보고하기위한 'snapt _ at '/' as _ of'.

7) 수정 및 호환성

SemVer: 'v1', 'v1. 1 '(확장),' v2 '-새로운 경로/네임 스페이스에서만 가능합니다.
진화 규칙: 창을 통해 필드/값 만 추가하고 "제거 → 제거" 합니다.
호환성 테스트: "테스트 계약" (소비자 중심).

8) 이벤트, 웹 후크 및 영수증

AsyncAPI는 테마/페이로드/서명을 설명합니다.

캡션: HMAC/EdUSA, 헤더 'X-Signature', 'X-Nonce', 'X-Timestamp' (좁은 창)

영수증: 중요한 이벤트 (지불, RTP/제한 변경, 가격 목록) 에 대한 '영수증 _ 해시' 및 DSSE 서명.
Retrai and dedup: 'dedempotency _ key '/' event _ id' 에 따른 demempotency.
DLQ/검역: 원인이있는 유효하지 않은/반복 된 보고서.

9) 관찰 가능성과 품질

추적: 게이트웨이/비즈니스 이벤트/웹 후크를 통한 필수 'trace _ id/span _ id'.
메트릭: 가용성, p50/p95/p99, 오류율, 재 시도율, 1k 당 비용.
통나무: 구조화 된 비밀/PII 없음; '테넌트/지역/버전' 레이블.
SLO/경고: SLO 지향 조건 및 자동 룬 (일시 정지/재 경로/롤백).

10) 오류 및 상태 의미론

2xx - 성공 (비동기 작업의 경우 202).
4xx-클라이언트의 결함 (422-유효성 검사, 409-충돌/idempotency, 429-한계).
5xx-일시적인 문제.
오류 본문: '코드', '메시지', 'trace _ id', '힌트', '다시 시도'? '.
파트너를위한 UX: 각 오류에 대해 "수행 할 작업" 테이블.

11) 코드 정책 (OPA/ABAC)

중앙 집중식 승인: "누가/무엇/어디서/언제/왜".
Git의 정책, 코드 검토, CI 테스트 (비행 전: "정책이 허용합니까? »).

SoD 확인: "결제를 생성하십시오"

12) 보안, 개인 정보 보호, 규정 준수

PII 최소화: 토큰 화/마스크, 승인 된 bs을 통해서만 기본에 액세스.
비밀: Vault/KMS, 짧은 TTL, 회전; 공유 비밀 금지.
암호화: mSL/TLS 1. 3, 적절한 경우 AES-GCM 정지, HSTS/PKP.
관할권 인식-지역 당 데이터/키의 현지화.
감사 로그: WORM, 머클 슬라이스, DSSE 서명.

13) 작동: SLI/SLO 및 대시 보드

• 경로 별/지역별 가용성.
• p95 대기 시간 (읽기/쓰기).
• 웹 후크의 성공 (영수증), 배송 지연.
• 오류율/재생률.
• 1k 요청 및 출구 당 비용.

SLO (예): 99. 95% 가용성; p95 λ120/250 ms; 웹 후크는 99 이상입니다. 5 %/5 분; P1 MTTR 체크 60 분

14) 관리 변경 (릴리스/롤백)

게이트웨이 및 중요 경로를위한 Blue-Green/Canary.
방출 금지 동작에 대한 Ficheflags.
스키마 및 페이로드에 대한 → Migrate → 계약 확장.
사용자 정의: 롤백 릴리스, 플래그 사용하지 않기, 재경로, 플러시 캐시.
아티팩트: 서명 된 이미지/표현, 버전 레지스트리.

15) SDK, 클라이언트, 샌드 박스

동일한 오류 및 리트레이 의미를 갖는 공식 SDK (TS/Java/Python/Go).
테스트 키/인증서 및 PSP/KYC/컨텐츠 제공 업체 시뮬레이터가있는 샌드 박스 환경.
계약 테스트는 CI SDK, 야간 호환성에 포함됩니다.

16) 데이터 모델 (단순화)

'api _ key' '{id, 테넌트, 스코프 [], ttl, 생성 _ by}'

'rate _ plan' '{테넌트, 쿼터 {경로 → 캡}, 버스트, 우선 순위}'

(PHP 3 = 3.0.6, PHP 4)

'webhook _ indication' '{이벤트 _ id, 종점, 상태, 시도, 영수증 _ hash, 서명}'

'policy' '{버전, 규칙, 서명자, dsse}'

17) RACI

18) 품질 지표

계약 드리프트: 0 "깨기" 변경 사항 없음.
Idempotency 오류 속도는 다음과 같습니다. 01%.
웹훅 성공: 99 이상. 5%, 지연 p95 소 60 초.

Auth Fail vs Abuse: 악의적 인 블록 공유, 노이즈

비용/1k: 경로 및 지역별 제어 (예산/상한 경고).
채택 SDK: 공식 SDK를 통한 트래픽 비율.

19) 사건 플레이 북

스파이크 429/한계: 골드 캡 인상, "잡음" 키 조절, 파트너와의 연결.
WebhookLag: 작업자/배치를 늘리고 대기열의 우선 순위를 정하고 일시적으로 웹 후크 옵션을 끄십시오.
PriceMismatch (카탈로그/FX/세금): 버전 조정, 캐시 포스 장애, 아티팩트 롤백, 보상.
PSP 중단: 경로 전환, "회색" 거래 검역, 재생.
API 키 타협: 지난 30 일 동안의 즉각적인 리콜, 로테이션, 감사.

20) iGaming/fintech의 특성

RTP/Limits API: 집계 및 프로파일 버전 만; 영수증으로 변경.
지불/지불: 202 개 이상의 서명 된 웹 후크; 키 demempotency를 주문하십시오.
제휴: 전환 결정, 분쟁에 대한 에스크로, 서명 된 보고서.
책임있는 플레이: 한계 및 RG 이벤트에 대해 "가드 레일 API" 를 노출하십시오.

21) 구현 점검표

• 설명 된 계약 (OpenAPI/AsyncAPI), CI 검증 및 소비자 테스트.
• 중요한 경로에 대한 OAuth2/OIDC, 스코프, JIT 비밀 및 mTLS를 구성했습니다.
• Idempotency, retrai, DLQ 및 검역소가 도입되었습니다.
• 모자/쿼타/우선 순위 및 경고.
• Cursor pagination, 'as _ of' 일관된 샘플.
• 검증 및 비난 정책.
• 서명/영수증, 재생 및 디드 업이있는 웹 후크.
• 추적/메트릭/로그, SLO 및 룬.
• WORM 로그, DSSE 서명, 머클 슬라이스.
• SDK, 샌드 박스, 시뮬레이터, 코드 샘플 및 방법.

22) FAQ

장기 작업의 경우 왜 202입니까?
연결을 유지하지 않고 웹 후크를 통해 안정적인 재 트레이/영수증을 제공합니다.

OpenAPI와 AsyncAPI가 모두 필요합니까?
예: 명령/요청에 대한 동기화, 이벤트/상태 협상에 대한 동기화.

변화를 피하는 방법?
추가 전용 규칙, 제거 → 관찰 → 제거, 고객 테스트 계약.

영수증을 어디에 보관해야합니까

서명이있는 WORM 영역에서; 'degress _ hash' 가 클라이언트로 반환되고 요청시 확인됩니다.

요약: API를 통한 작업은 엄격한 액세스 모델 및 demempotency, 한계 및 버전, 관찰 가능성 및 SLO, 서명 및 영수증 등 계약 및 운영 분야입니다. 샌드 박스와 SDK를 추가하면 파트너는 빠르고 안전하며 예측 가능하게 통합되며 비즈니스는 품질이나 규정 준수를 잃지 않고 확장됩니다.