생태계 API

(섹션: 생태계 및 네트워크)

1) 목표와 원칙

• 빠르고 예측 가능한 통합 (Time-to-Integration).
• 신뢰성 및 확장 성 (SLO, QoS, 역압).
• 안전 및 준수 (최소 권리, 감사).
• 고장없는 진화 (버전, 호환성, 변형).

원칙: 계약 우선, 데이터 최소화, demempotency, 기본적으로 관찰 가능성, 릴리스의 "두 가지 속도" (코어 대 실험).

2) API 분류법

1. REST/HTT-동기 CRUD/명령 작업, demempotency 키, 페이지 매김/커서.
2. gRPC/QUIC-낮은 대기 시간, 스트림, 이진 프로토콜.
3. 이벤트 (펍/서브) - 도메인 이벤트 ('예금. ',' 지불. ',' 다리. ',' 위험. ').
4. Webhooks-서명 및 배상이 포함 된 리버스 알림.
5. GraphQL (제한적) -구체화 된 상점에 대한 총 판독 값.
6. 관리자/메타-디렉토리, 버전, 상태, 키, 할당량.

액세스 수준: 공개 (제한된 방법/읽기), 파트너 (스코프 및 할당량), 내부 (개인 윤곽).

3) 계약 및 계획

OpenAPI/AsyncAPI/Protoguy IDL은 단일 진실의 원천입니다.
데이터 계약-호환성 테스트, 회로 라인터, MAJOR없이 "파괴" 필드 금지.
카탈로그: 자산/네트워크, PSP/방법, 지역/관할 구역, SDK 버전, 기능 플래그.

최소 REST 계약 (OpenAPI 조각)

yaml openapi: 3. 0. 3 info: { title: Ecosystem Core API, version: "2. 6. 0" }
paths:
/v2/payouts:
post:
operationId: createPayout parameters:
- in: header name: Idempotency-Key required: true schema: { type: string, maxLength: 64 }
requestBody:
required: true content:
application/json:
schema:
$ref: "#/components/schemas/PayoutRequest"
responses:
"202": { $ref: "#/components/responses/Ack" }
"409": { description: "Duplicate (idempotent)" }
components:
schemas:
PayoutRequest:
type: object required: [amount, currency, destination]
properties:
amount:  { type: string, pattern: "^[0-9]+(\\.[0-9]{1,9})?$" }
currency: { type: string, example: "USD" }
destination: { type: string }
metadata: { type: object, additionalProperties: true }

이벤트 (AsyncAPI)

yaml asyncapi: 2. 6. 0 info: { title: Ecosystem Events, version: "1. 9. 0" }
channels:
payout. finalized:
subscribe:
message:
name: PayoutFinalized payload:
type: object required: [id, ts, amount, currency, status, signature]
properties:
id: { type: string }
ts: { type: string, format: date-time }
amount: { type: string }
currency: { type: string }
status: { type: string, enum: ["finalized","failed"] }
signature: {type: string} # source signature

4) 수정 및 호환성

SemVer: 'MAJOR. 미노르. PATCH '. MINOR/PATCH-역 호환; 메이저 - 병렬 버전 ('/v1 ', '/v2') + 어댑터.
거부 정책: 90 일 이상 창, "두 줄" 지원, 계약에 대한 자동 알림.
기능 플래그: 지역/파트너별로 필드/메소드를 활성화/비활성화합니다.
역량 협상: 악수 할 때 지원되는 프로필을 선언합니다.

5) 이데올로기, 주문 및 커서

명령에 대한 Idempotency-Key (생성/취소), TTL 키는 72 시간 이상입니다.
아웃 박스/받은 편지함 및 demempotent 소비자를 통한 정확한 의미론.
커서에 의한 페이지 분석: '다음 _ 커서', 삽입/삭제에 대한 저항.

정렬 및 필터는 안정적이고 명확하게 문서화되어 있습

6) 보안과 신뢰

mSL (서비스 서비스), 종자 고정 및 키 회전.
채널에 바인딩하기위한 OAuth2/OIDC (클라이언트 자격 증명, TTL이 짧은 JWT), PoP/DPoP.
Webhook 서명 (NMAS/key 버전/시간), 반복 보호.
RBAC/ABAC 및 PoLP: scopes, org _ id/tentent _ id, 객체/작동 제한.
DLP/PII 최소화: 레이블/로그의 PII 금지, 식별자의 토큰 화.
속도 제한 및 WAF: org/route/region에 따라, 남용 방지.

샘플 키 정책 (YAML)

yaml auth:
oauth2:
issuer: "https://auth. ecosys"
jwks_uri: "https://auth. ecosys/.well-known/jwks. json"
token_ttl_s: 900 mtls:
required_for: ["internal","partner_p0"]
scopes:
- name: payouts:write
- name: payouts:read
- name: events:subscribe

7) 쿼타, QoS 및 역압

QoS 클래스: P0 (결제/브리지/최종), P1 (제품), P2 (벌크/아카이브).
쿼터/제한: 이벤트에 대한 RPS, 동의 요청, 바이트/초, 주제/파티.
입학 통제: "비싼" 요청의 조기 거부, 무거운 쿼리 보호.
배압: 토큰/크레딧, DLQ 대기열, 지터로 재조정.

쿼터 정책

yaml quotas:
partner_default:
rps: 200 concurrent: 100 webhooks_outbound_rps: 50 p0:
rps: 100 p95_latency_ms: 400

8) 관찰 가능성: SLI/SLO, 지표, 흔적

• p95/99 대기 시간
• 계약 준수% (스키마/서명).
• 웹 후크 재 시도/삭제%.

SLO: P0 p95 95%; 웹훅 전달 p95 이벤트 신선도 p95

지표: 대기 시간 히스토그램, 오류 코드, 응답 크기, RPS, 임차인 당.
추적: 엔드 투 엔드 'trace _ id' (에지 → 게이트웨이 → 서비스 → DB → 이벤트/웹 후크).
로그: PII없이 '요청 _ id' 로 상관 관계를 구성합니다.

9) 다운 타임 프리 릴리스 패턴

SLO 게이트 및 특이 치 배출이있는 Blue-Green/Canary.
스키마 최초의 진화: 오래된 고객을위한 필드, 어댑터 만 추가하십시오.
다운 타임 제로 데이터베이스 마이그레이션: 온라인 DDL, 양방향 변환기.
제어 변경: 타임 록, 감사 및 호환성 레지스트리.

10) 카탈로그 및 레지스터

API/버전 등록

sql
CREATE TABLE api_registry(
name TEXT, kind TEXT,      -- rest    grpc    events    webhook version TEXT, status TEXT,   -- active    canary    deprecated    retired slo JSONB, owner TEXT,
PRIMARY KEY (name, version)
);

이벤트 카탈로그

sql
CREATE TABLE event_catalog(
topic TEXT PRIMARY KEY,
schema_version TEXT,
qos TEXT,
retention_days INT,
pii BOOLEAN DEFAULT false
);

키/스코프

sql
CREATE TABLE api_keys(
key_id TEXT PRIMARY KEY,
org_id TEXT, scopes TEXT[], status TEXT, expires_at TIMESTAMPTZ
);

11) 계약 준수 테스트 및 준수

계약 테스트: 클라이언트 생성, 스키마 검증, negative-_ cases.
이벤트 테스트 재생: 반복/재정렬 저항.
혼돈/위도 테스트: 손실/지터 주사, 느린 스토르.
보안 테스트: 웹 후크 서명, 키 회전, 재생 공격.
성능 프로파일: SLA 스파이크, 핫 루트, DA/의존성 브리지.

12) 인터페이스의 예

웹 후크 (서명 및 retrai)

yaml webhooks:
deliveries:
retry:
attempts: 5 backoff_ms: [200, 800, 1600, 3200, 6400]
jitter: true signature:
alg: "HMAC-SHA256"
header: "X-ECO-Signature"
timestamp_header: "X-ECO-Timestamp"
tolerance_s: 300

GraphQL (읽기 읽기, 읽기 만)

graphql type Query {
payouts(status: [Status!], first: Int!, after: String): PayoutConnection!
}

gRPC (이벤트 흐름)

proto service EventStream {
rpc Subscribe(SubscribeRequest) returns (stream Event);
}

13) 프로세스 및 역할

API 소유자 - 계약/버전/SLO/쿼터.
보안-키/서명/감사/DLP.
SRE/Ops-대시 보드, 경고, 용량.
파트너 성공-온 보딩, 한계, phicheflags.
준수-관할 구역, 제재, 보고.

14) 대시 보드

핵심 API: 경로 및 텐트 별 대기 시간/오류/RPS.
웹 후크: 배달 p95, 재 시도, 낙하, 서명.
이벤트: 신선도, 지연, 소비자 건강, DLQ.
보안: 만료 키, 서명, 요청 거부.
거버넌스: 활성 버전/사용하지 않음, 계약 호환성.

15) 플레이 북 사건

A. p95 대기 시간 P0의 성장

1. P0 및 P2 스로틀 우선 순위 사용; 2) 스케일 게이트웨이;

2. 읽기의 일부를 캐시 4) "핫" 경로 분석으로 전환하십시오.

B. 배달 웹 후크 드롭

1. 서명/시간 이동 확인, 2) 배상/타임 아웃 증가,

2. 배치를 켜십시오. 4) 일시적으로 총알 끝점으로 전환합니다.

C. 드리프트 계약

1. "엄격한 모드" 사용

2. 생산자에게 알리기, 3) 어댑터 해제, 4) 사후 부검, 라인터 업데이트.

D. Key/cert 타협

1. 철회/회전, 2) 웹 후크 재생, 3) 감사, 4) 파트너에게 알립니다.

E. 반복/폭발

1. Check Idempotency-Key/TTL, 2) 데드 업 강화, 3) "잡음" 소스를 제한합니다.

16) 구현 점검표

1. 계약 (OpenAPI/AsyncAPI/IDL) 을 설명하고 라인터 및 CI를 포함합니다.

2. (PHP 3 = 3.0.6, PHP 4)

3. 쿼터/QoS/한계, 쿼리 보호 및 역압을 입력하십시오.
4. 관찰 가능성 향상: SLI/SLO, 트랙, 대시 보드, 경고.
5. 조직 릴리스: 카나리아/청록색, 스키마 우선 마이그레이션.
6. 버전/이벤트/키 디렉토리를 시작하고 프로세스를 취소하십시오.
7. 혼돈/perf/보안 테스트를 수행하고 플레이 북을 정렬하십시오.
8. 데이터 최소화 및 규제 준수를 정기적으로 개선합니다.

17) 용어집

계약 우선-공식 계약을 통한 코드 설계.
Idempotency-Key-작업을 안전하게 반복하는 키입니다.
AsyncAPI-이벤트 인터페이스 사양.
QoS - 서비스 품질/우선 순위 클래스.
DLQ- 문제 메시지에 대한 "데드 큐".
오류 예산 연소-SLO에 대한 오류 예산을 "연소" 하는 속도.

결론: 생태계 API는 일련의 종점이 아니라 관리 된 계약, 보안, 할당량 및 관찰 시스템입니다. 이 프레임 워크를 따라 생태계는 네트워크 계층 및 인증에서 이벤트 흐름 및보고에 이르기까지 다운 타임없이 빠른 통합, 예측 가능한 SLO 및 안전한 진화를 얻습니다.