최영선의 블로그

문서가 부족한 API는 기능이 없어서 외면받는 경우보다, 첫 호출까지 가는 길이 너무 길어서 포기되는 경우가 더 많습니다. 팀 안에서는 아는 사람이 구두로 메워 주지만, 외부 사용자는 그 빈칸을 메워 줄 동료가 없기 때문에 문서 품질이 곧 도입 속도가 됩니다.여기서는 좋은 API 문서를 reference 모음이 아니라 채택 경로 전체로 봅니다. Getting Started, 시나리오 튜토리얼, 예제 중심 reference, changelog, SDK 안내가 어떻게 한 흐름으로 이어져야 하는지 정리합니다.API Design 101 10장 흐름 개요문서가 좋다는 것은 정보량이 많다는 뜻이 아닙니다. 사용자가 지금 필요한 정보를 최소 클릭으로 찾을 수 있다는 뜻입니다.먼저 던지는 질문API 문서는 어떤 다섯 ..

API를 오래 운영하다 보면 진짜 어려운 일은 바꾸는 것 자체보다 바꿀 때 신뢰를 잃지 않는 일입니다. 필드 하나를 추가하는 순간에는 사소해 보여도, 어떤 팀은 즉시 배포하고 어떤 팀은 반년 뒤에야 따라오기 때문에 호환성 규칙이 없는 변화는 곧 장애 공지가 됩니다.여기서는 versioning을 URL 문법이 아니라 변경 관리 절차로 다룹니다. 무엇이 breaking인지 먼저 정의하고, 그다음 URL·header·deprecation·sunset을 어떤 조합으로 운영할지 차례로 정리합니다.API 변경이 호환성 판단 → 버전 결정 → deprecation 공지 → sunset 순서로 진행되는 흐름먼저 던지는 질문breaking change와 non-breaking change는 어떻게 구분할까요?URL ve..

문서가 코드보다 늦게 갱신되기 시작하는 순간, 팀은 문서를 참고하지 않고 직접 호출해 보는 습관을 들이게 됩니다. 그 단계까지 가면 문서는 설명서가 아니라 의심 대상이 되고, SDK와 테스트도 같은 방향으로 어긋납니다.여기서는 OpenAPI와 Swagger를 문서 도구가 아니라 계약 자동화 체계로 봅니다. 하나의 spec이 validation, 예제, SDK, mock server까지 연결되어야만 단일 진실 원본이라는 말이 실제 운영 습관으로 이어집니다.OpenAPI spec 하나가 문서, 검증, SDK, mock을 동시에 구동하는 구조먼저 던지는 질문OpenAPI 3 문서는 어떤 구조로 이루어질까요?Swagger UI와 Redoc은 각각 어떤 역할을 할까요?code-first와 schema-first는..

성공 응답은 한두 개만 잘 맞춰도 눈에 잘 띄지 않지만, 에러 응답은 조금만 흔들려도 바로 운영 비용으로 돌아옵니다. 지원 요청은 늘고, 클라이언트는 예외 분기를 늘리고, 로그에서는 같은 실패가 여러 모양으로 찍히기 시작합니다.여기서는 에러를 부가 정보가 아니라 정식 계약으로 다룹니다. 상태 코드, machine-readable code, validation detail, trace id가 어떻게 함께 움직여야 디버깅과 보안이 동시에 버틸 수 있는지 정리합니다.에러가 발생하면 status code → error code → detail → trace id 순서로 응답이 구성되는 흐름먼저 던지는 질문좋은 error response는 어떤 요소로 이루어질까요?RFC 7807 application/proble..

목록 API는 처음에는 금방 만들 수 있어 보여도, 데이터가 쌓이는 순간 가장 먼저 흔들리는 지점이 됩니다. 느려진 쿼리, 중복 응답, 누락된 항목이 한꺼번에 나타나기 시작하면 파라미터 이름 하나도 쉽게 바꾸지 못합니다.여기서는 pagination, sorting, filtering을 단순 옵션 모음이 아니라 성능과 정확성을 함께 지키는 계약으로 정리합니다. 특히 offset과 cursor의 선택이 어떤 운영 비용을 만드는지까지 같이 봅니다.클라이언트 요청이 filter → sort → paginate 순서로 처리되는 흐름먼저 던지는 질문offset / limit 방식은 어디까지 단순하고 어디서부터 한계가 드러날까요?cursor 기반 pagination은 어떤 문제를 해결하며 어떤 것을 포기할까요?sor..

처음에는 JSON 몇 줄만 맞추면 되는 것처럼 보여도, 시간이 지나면 가장 자주 깨지는 부분이 바로 schema입니다. 필드 이름 하나, 날짜 형식 하나, null 허용 여부 하나가 클라이언트 파싱 로직과 데이터 정합성 문제로 바로 이어집니다.여기서는 schema를 단순 문서 항목이 아니라 경계에서 강제해야 할 계약으로 다룹니다. 입력 검증, 응답 직렬화, 시간과 금액 표현을 함께 정리해야 나중에 버전 관리 비용도 줄어듭니다.API Design 101 5장 흐름 개요먼저 던지는 질문JSON과 content type은 어떤 식으로 계약에 들어갈까요?필드 이름 규칙은 어떻게 정해야 할까요?validation은 어디에서, 어떤 방식으로 해야 할까요?왜 중요한가schema가 흔들리면 클라이언트도 함께 흔들립니다..

같은 작업을 해도 어떤 API는 클라이언트가 다음 행동을 쉽게 고르고, 어떤 API는 성공인지 실패인지부터 다시 해석하게 만듭니다. 그 차이는 대개 메서드 이름이 아니라 method와 status code를 얼마나 일관되게 묶어 썼는지에서 나옵니다.여기서는 GET, POST, PATCH, DELETE를 단순 암기가 아니라 클라이언트 분기 규칙으로 정리합니다. 응답 숫자를 어떻게 고르느냐가 재시도, 캐시, 에러 처리까지 함께 결정하기 때문입니다.API Design 101 4장 흐름 개요먼저 던지는 질문GET, POST, PUT, PATCH, DELETE는 각각 무엇을 의미할까요?safe와 idempotent는 어떻게 다를까요?2xx, 3xx, 4xx, 5xx 계열은 어떻게 읽어야 할까요?왜 중요한가meth..

URL은 한 번 공개되면 데이터베이스 컬럼명보다 훨씬 오래 살아남습니다. 초기에 대충 붙인 경로 이름 하나가 나중에는 SDK, 문서, 캐시 키, 로그 필터까지 끌고 다니는 외부 계약이 됩니다.여기서는 좋은 REST URL을 예쁜 문자열이 아니라 리소스 모델의 결과물로 봅니다. 컬렉션 경계, 하위 리소스, 식별자 노출 범위를 먼저 정해야 뒤의 메서드와 문서가 함께 안정됩니다.API Design 101 3장 흐름 개요먼저 던지는 질문리소스의 경계는 어떻게 나눠야 할까요?명사형 이름, 복수형, 계층 구조는 어떤 원칙으로 잡아야 할까요?하위 리소스는 언제 쓰고 어디까지 깊게 들어가야 할까요?왜 중요한가URL은 한 번 공개되면 바꾸는 비용이 큽니다. SDK, 캐시 키, 로그 필터, 문서 링크가 모두 그 경로를 참..

비슷해 보이는 두 API가 실제로는 전혀 다르게 느껴지는 이유는 대개 REST라는 이름 때문이 아니라 예측 가능성 때문입니다. URL은 그럴듯한데 호출할 때마다 규칙이 달라지면, 클라이언트는 문서를 읽고도 계속 추측해야 합니다.여기서는 REST를 URL 스타일이 아니라 여섯 가지 제약이 만드는 설계 규율로 정리합니다. 그래야 이후 글에서 리소스, 메서드, 캐시, 문서 구조를 따로 배워도 같은 방향으로 이해할 수 있습니다.REST의 계층 구조: 클라이언트 → 캐시/LB → 서버 → 데이터먼저 던지는 질문REST는 어디서 나왔고 무엇을 뜻할까요?REST를 이루는 여섯 가지 아키텍처 제약은 무엇일까요?리소스 중심 사고는 RPC 스타일과 어떻게 다를까요?REST의 탄생과 핵심 정의REST(Representati..

팀이 같은 기능을 각자 다른 방식으로 호출하기 시작하면, 그때부터 구현 문제가 아니라 계약 문제가 터집니다. 서버 코드는 멀쩡한데도 호출 규칙이 흐릿하면 클라이언트마다 다른 가정을 붙이고, 작은 변경이 바깥에서는 장애처럼 번집니다.여기서는 API를 단순한 함수 호출이나 URL 집합이 아니라, 오래 유지해야 하는 외부 계약으로 보는 관점을 먼저 세웁니다. 그래야 이후 글에서 다룰 REST, 리소스, 상태 코드, 문서화 원칙이 한 흐름으로 연결됩니다.클라이언트와 서버 사이에 API 계약이 놓이는 구조먼저 던지는 질문API는 정확히 무엇이며, 왜 시스템의 외부 계약이라고 부를까요?라이브러리 API와 웹 API는 무엇이 같고 무엇이 다를까요?좋은 API라고 부르려면 어떤 조건을 갖춰야 할까요?API란 정확히 무..