# API 설계, 인터페이스의 철학

# API 설계, 인터페이스의 철학  API는 단순한 기술 명세가 아니다. 시스템 간 계약이자 사유의 구조다. 좋은 API는 명확한 의도, 일관된 규칙, 그리고 변화에 대응하는 유연성을 동시에 갖춘다. 이 글은 REST 원칙부터 버저닝, 에러 처리까지 실전에서 마주하는 설계 문제의 본질을 탐구한다. ---  ## 계약으로서의 API API(Application Programming Interface)는 소프트웨어가 세계와 맺는 계약이다. 함수 하나, 엔드포인트 하나가 모두 약속이며, 그 약속이 깨지는 순간 시스템은 무너진다. 개발자는 흔히 API를 '데이터를 주고받는 통로'쯤으로 여기지만, 그것은 표층에 불과하다. API 설계의 본질은 의도를 명료하게 드러내고, 오용을 구조적으로 차단하며, 미래의 변화를 수용할 여지를 남기는 것이다. 좋은 API는 문서를 읽지 않아도 직관적이다. 나쁜 API는 문서를 아무리 읽어도 혼란스럽다. 이 차이는 기술적 역량이 아닌 사유의 깊이에서 발생한다.  코드는 컴퓨터를 위해 쓰지만, API는 사람을 위해 설계한다. 인터페이스란 결국 인간의 의도를 기계적 규약으로 번역하는 행위다. 이 글은 REST 아키텍처의 원리에서 시작해, 네이밍, 버저닝, 에러 처리, 보안에 이르기까지 API 설계의 핵심 원칙을 다룬다. 단순한 베스트 프랙티스 나열이 아니라, 각 원칙이 왜 존재하며 어떤 문제를 해결하는지 그 구조를 밝히고자 한다. --- ## REST의 논리: 자원, 행위, 표현  RESTful API는 유행이 아니다. Roy Fielding이 제시한 REST(Representational State Transfer)는 웹의 본질적 특성을 API 설계에 투영한 아키텍처 스타일이다. 그 핵심은 세 가지 개념의 분리에 있다. 자원(Resource)은 API가 다루는 대상이다. 사용자, 게시글, 주문, 결제 등 모든 개체가 자원이 된다. REST는 이 자원을 URI로 식별한다. `/users/123`은 123번 사용자를, `/orders/456`은 456번 주문을 가리킨다. 여기서 중요한 것은 URI가 행위가 아닌 명사, 즉 자원 자체를 지시한다는 점이다. `/getUser`나 `/deleteOrder` 같은 표현은 REST 원칙에서 벗어난다. 행위(Verb)는 HTTP 메서드로 표현한다. GET은 조회, POST는 생성, PUT은 전체 수정, PATCH는 부분 수정, DELETE는 삭제다. 이 메서드들은 자원에 대한 표준화된 동작을 정의한다. `GET /users/123`은 "123번 사용자를 조회하라"는 의미며, `DELETE /users/123`은 "123번 사용자를 삭제하라"는 뜻이다. 메서드와 URI의 결합으로 의도가 명확해진다. 표현(Representation)은 자원의 상태를 어떤 형식으로 전달할지를 다룬다. 같은 사용자 자원이라도 JSON, XML, HTML 등 다양한 형태로 표현될 수 있다. Content-Type 헤더가 이를 명시한다. REST는 자원 자체와 그 표현을 분리함으로써, 클라이언트가 필요한 형식을 요청할 수 있는 유연성을 제공한다. 이 세 요소의 분리는 형식미가 아니다. 자원과 행위를 분리하면 API가 예측 가능해지고, 표현을 분리하면 확장 가능해진다. 개발자는 `/users` 엔드포인트만 보고도 GET, POST, PUT, DELETE가 모두 가능하리라 예상할 수 있다. 이것이 REST가 '직관적'이라 불리는 이유다. --- ## 네이밍의 질서: 일관성과 명료함 API에서 이름은 단순한 식별자가 아니다. 그것은 설계자의 의도를 전달하는 언어이며, 사용자가 시스템을 이해하는 첫 번째 경로다. 좋은 네이밍은 주석을 대체하고, 나쁜 네이밍은 혼란을 양산한다. 명사를 사용하라. URI는 자원을 지시하므로 명사형이 자연스럽다. `/users`, `/products`, `/orders`처럼 복수형 명사를 쓰는 것이 일반적이다. 단수형도 가능하지만, 컬렉션을 다룰 때 복수형이 더 직관적이다. `/users`는 사용자 목록을, `/users/123`은 특정 사용자를 의미한다는 구조가 명확하다. 동사를 피하라. `/getUser`, `/createOrder` 같은 표현은 REST 원칙에 어긋난다. 행위는 HTTP 메서드가 담당하므로, URI에 중복 표기할 필요가 없다. 예외는 있다. `/search`, `/login`, `/logout`처럼 특정 행위 자체가 자원으로 간주될 때는 동사 사용이 허용된다. 하지만 이는 최소화해야 한다. 계층 구조를 활용하라. `/users/123/orders`는 "123번 사용자의 주문 목록"을 의미한다. 이런 계층적 표현은 자원 간 관계를 명확히 드러낸다. 단, 깊이가 3단계를 넘어가면 가독성이 떨어진다. `/users/123/orders/456/items/789`보다는 `/order-items/789`처럼 단축하는 편이 낫다. 케이스를 통일하라. `camelCase`, `snake_case`, `kebab-case` 중 하나를 선택해 일관되게 적용해야 한다. REST API에서는 `kebab-case`가 선호되는 경향이 있다. `/user-profiles`, `/order-histories`처럼 URL에 자연스럽게 녹아들기 때문이다. 중요한 것은 선택 그 자체보다 일관성이다. 필터와 정렬은 쿼리 파라미터로 처리하라. `/users?status=active&sort=created_at`처럼 조건을 URI 경로가 아닌 파라미터로 전달하면, 같은 자원에 대한 다양한 뷰를 유연하게 제공할 수 있다. 경로는 자원의 정체성을, 파라미터는 표현 방식을 담당한다. --- ## 버전 관리: 변화를 설계하기 API는 태생적으로 불완전하다. 비즈니스 요구사항은 변하고, 기술 스택은 진화하며, 설계 실수는 뒤늦게 발견된다. 문제는 API가 일단 공개되면 되돌릴 수 없다는 점이다. 클라이언트는 이미 그것에 의존하고 있으며, 호환성을 깨뜨리는 순간 시스템 전체가 마비된다. 버저닝(Versioning)은 변화를 수용하면서도 기존 계약을 유지하는 전략이다. 가장 명시적인 방법은 URI에 버전을 포함하는 것이다. `/v1/users`, `/v2/users`처럼 경로에 버전 번호를 명기하면, 구버전과 신버전이 명확히 분리된다. 이 방식은 직관적이지만, URI가 자원이 아닌 버전을 포함한다는 점에서 REST 순수주의자들의 비판을 받는다. 그러나 실용성 측면에서 가장 널리 쓰인다. 헤더를 활용하는 방법도 있다. `Accept: application/vnd.myapi.v2+json`처럼 Content Negotiation을 통해 버전을 지정한다. URI는 깔끔하게 유지되지만, 버전 정보가 눈에 보이지 않아 디버깅이 어렵다는 단점이 있다. API 문서에서 명시적으로 안내하지 않으면, 사용자가 버전 존재 자체를 모를 수도 있다. 쿼리 파라미터를 쓰는 방식도 있다. `/users?version=2`처럼 버전을 파라미터로 전달한다. 구현은 간단하지만, 버전이 자원의 속성처럼 보여 의미론적으로 혼란스럽다. 일반적으로 권장되지 않는다. 버저닝에서 더 중요한 것은 언제 버전을 올릴 것인가다. 하위 호환성이 깨지는 변경(Breaking Change)이 발생할 때만 메이저 버전을 올려야 한다. 필드 추가나 선택적 파라미터 추가는 기존 클라이언트에 영향을 주지 않으므로, 같은 버전 내에서 처리 가능하다. 반면 필드 삭제, 타입 변경, 필수 파라미터 추가는 호환성을 파괴하므로 새 버전이 필요하다. 구버전 지원 기간도 미리 정책으로 명시해야 한다. "v1은 v2 출시 후 6개월간 지원"처럼 명확한 기한을 제시하면, 클라이언트가 마이그레이션을 계획할 수 있다. 무기한 지원은 기술 부채를 축적시킬 뿐이다. --- ## 에러 처리: 실패의 언어 에러는 예외 상황이 아니라 정상적인 통신의 일부다. 인증 실패, 권한 부족, 잘못된 요청, 서버 오류 등 API는 수많은 이유로 실패한다. 좋은 에러 설계는 무엇이 잘못되었는지, 어떻게 해결할 수 있는지를 명확히 전달한다. HTTP 상태 코드는 에러의 범주를 나타낸다. 2xx는 성공, 4xx는 클라이언트 오류, 5xx는 서버 오류다. 세부적으로는 400(잘못된 요청), 401(인증 실패), 403(권한 없음), 404(자원 없음), 409(충돌), 500(서버 오류), 503(서비스 불가) 등을 구분한다. 상태 코드만으로도 문제의 주체(클라이언트 vs 서버)와 성격(인증 vs 권한 vs 데이터)을 파악할 수 있다. 하지만 상태 코드만으로는 부족하다. 401 에러가 발생했을 때, 토큰이 만료된 것인지 아예 없는 것인지 알 수 없다면 클라이언트는 대응할 수 없다. 에러 응답 본문에는 구조화된 정보가 필요하다. ```json { "error": { "code": "INVALID_TOKEN", "message": "인증 토큰이 만료되었습니다.", "details": { "expired_at": "2026-05-11T10:30:00Z" }, "suggestion": "로그인을 다시 시도하세요." } } ``` 이 구조는 네 가지 정보를 담는다. `code`는 기계가 읽을 수 있는 고유 식별자다. 클라이언트는 이를 기반으로 분기 처리할 수 있다. `message`는 사람이 읽을 수 있는 설명이다. `details`는 추가 컨텍스트를 제공한다. `suggestion`은 해결 방안을 안내한다. 일관된 에러 형식은 클라이언트 코드를 단순화한다. 모든 API가 같은 구조로 에러를 반환하면, 공통 에러 핸들러를 작성할 수 있다. 반대로 엔드포인트마다 에러 형식이 다르면, 각각을 별도로 처리해야 하므로 복잡도가 급증한다. 보안 측면에서는 과도한 정보 노출을 피해야 한다. 내부 스택 트레이스나 데이터베이스 에러 메시지를 그대로 반환하면, 공격자에게 시스템 구조를 알려주는 셈이다. 개발 환경에서는 상세 로그를 남기되, 프로덕션에서는 일반화된 메시지만 노출하는 것이 원칙이다. --- ## 보안: 신뢰의 구조 API는 공개된 인터페이스이므로 본질적으로 취약하다. 인증(Authentication)과 인가(Authorization)는 이 취약성을 통제하는 핵심 메커니즘이다. 인증은 "당신이 누구인가"를 확인하는 과정이다. 가장 기본적인 방식은 API 키다. 클라이언트가 요청 헤더에 키를 포함하면, 서버가 이를 검증한다. 간단하지만 키가 노출되면 무방비 상태가 된다. 키는 환경 변수로 관리하고, HTTPS를 통해서만 전송해야 한다. OAuth 2.0은 더 정교한 인증 체계다. 사용자가 직접 비밀번호를 전달하지 않고, 인증 서버가 발급한 토큰을 사용한다. 토큰은 짧은 유효 기간을 가지며, 갱신 토큰(Refresh Token)을 통해 재발급할 수 있다. 이 방식은 자격 증명을 분산시켜 보안 위험을 최소화한다. 인가는 "당신이 무엇을 할 수 있는가"를 통제한다. 인증된 사용자라도 모든 자원에 접근할 수는 없다. 역할 기반 접근 제어(RBAC)는 사용자를 역할로 분류하고, 각 역할에 권한을 부여한다. 관리자는 모든 사용자를 조회할 수 있지만, 일반 사용자는 자신의 정보만 볼 수 있다. 속도 제한(Rate Limiting)은 남용을 방지한다. 짧은 시간에 과도한 요청을 보내면, 서버는 429(Too Many Requests) 상태로 응답한다. 이는 DDoS 공격을 완화하고, 서버 자원을 공정하게 배분하는 장치다. `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` 헤더로 제한 정보를 전달하면, 클라이언트가 요청 속도를 조절할 수 있다. 입력 검증은 모든 보안의 시작이다. 클라이언트에서 보내는 데이터는 신뢰할 수 없다. SQL 인젝션, XSS, 경로 순회 공격 등은 모두 입력 검증 실패에서 비롯된다. 서버는 모든 파라미터의 타입, 길이, 형식을 엄격히 검사해야 한다. --- ## 설계는 사유의 외연 API 설계는 코드를 넘어선 행위다. 그것은 시스템의 경계를 정의하고, 의도를 명시하며, 미래의 변화를 예측하는 지적 작업이다. REST 원칙은 자원과 행위를 분리함으로써 예측 가능성을 확보한다. 일관된 네이밍은 문서 없이도 직관적인 이해를 가능케 한다. 버저닝은 변화를 수용하면서도 안정성을 유지하는 전략이다. 에러 처리는 실패를 투명하게 드러내어 신뢰를 구축한다. 보안은 공개된 인터페이스가 통제된 방식으로만 작동하도록 보장한다. 좋은 API는 그 자체로 문서다. 엔드포인트 이름만 보고도 무엇을 하는지 알 수 있고, 에러 메시지만 읽어도 어떻게 해결할지 짐작할 수 있다. 이것은 기술이 아니라 철학의 문제다. 사용자의 입장에서 생각하고, 시스템의 본질을 꿰뚫으며, 변화를 설계에 포함하는 태도가 좋은 API를 만든다. 설계는 한 번에 완성되지 않는다. 초기 설계가 완벽할 수 없으므로, 피드백을 수용하고 점진적으로 개선해야 한다. 중요한 것은 모든 변경이 의도적이어야 한다는 점이다. 임시방편으로 쌓인 예외는 결국 기술 부채가 된다. 원칙을 세우고, 그것을 일관되게 적용하며, 필요할 때 의식적으로 이탈하라. 그것이 API 설계자의 책무다. 인터페이스는 시스템이 세계와 대화하는 방식이다. 그 대화가 명료할 때, 시스템은 신뢰받는다.