- resource
- http-method
- status-code
RESTful API를 설명해 주세요
- 예상 시간
- 6분
RESTful API는 서버 기능을 action 이름 중심으로 나열하기보다 resource 중심으로 설계하는 방식입니다.
예를 들어 user 목록은 /users, 특정 user는 /users/{id}처럼 표현하고, 조회는 GET, 생성은 POST, 수정은 PUT이나 PATCH, 삭제는 DELETE를 사용합니다.
응답도 200, 201, 400, 401, 404 같은 HTTP status code로 의미를 전달합니다. 중요한 점은 URL, method, status code가 일관되어 API를 예측 가능하게 만드는 것입니다.
REST는 Roy Fielding이 2000년 박사학위 논문에서 정리한 아키텍처 스타일이고, 원래는 특정 API 형식이 아니라 웹이 왜 이렇게까지 확장될 수 있었는지를 설명하는 제약 조건 모음입니다. 여섯 가지가 있습니다.
- client-server: 사용자 인터페이스와 데이터 저장을 분리한다.
- stateless: 각 요청은 처리에 필요한 정보를 스스로 다 담는다. 서버가 이전 요청을 기억하지 않는다.
- cacheable: 응답은 캐시 가능한지 여부를 표시한다.
- uniform interface: 리소스를 식별하고 표현으로 조작하는 방식이 일관된다.
- layered system: 클라이언트는 중간에 프록시나 캐시가 있는지 알 필요가 없다.
- code on demand: 서버가 실행 가능한 코드를 내려줄 수 있다(선택).
여기서 stateless와 cacheable이 왜 중요한지가 실무와 직결됩니다. 서버가 이전 요청을 기억하지 않아야 아무 서버나 그 요청을 처리할 수 있어서 수평 확장이 가능하고, 응답이 캐시 가능해야 중간 계층이 부하를 대신 받아줍니다.
실무에서 말하는 'RESTful API'는 이 중 uniform interface의 일부만 지키는 HTTP API인 경우가 대부분입니다. Fielding 본인도 그런 API를 REST라고 부르는 것에 문제를 제기한 적이 있습니다. 다만 면접에서 중요한 건 용어 심판이 아니라, 어떤 제약을 지키고 있고 무엇을 포기했는지 설명할 수 있는가입니다.
꼬리질문
답변 뒤에 이어질 수 있는 질문들을 하나씩 열어볼 수 있어요.
PUT과 PATCH는 어떻게 다른가요?
PUT은 resource 전체를 대체하는 의미로 설명되는 경우가 많고, PATCH는 일부 변경에 가깝습니다. 그래서 API 문서에 각 method의 의미를 정확히 적어 두는 것이 중요합니다.
둘을 섞어 쓰면 client가 기대하는 동작이 어긋날 수 있습니다.
차이를 가르는 실질적인 기준은 멱등성(idempotency)입니다. 같은 요청을 여러 번 보내도 결과가 한 번 보낸 것과 같으면 멱등합니다.
GET,PUT,DELETE: 멱등합니다.PUT은 리소스를 그 상태로 덮어쓰므로 열 번 보내도 결과가 같고,DELETE도 이미 지워진 걸 다시 지워도 최종 상태는 같습니다.POST: 멱등하지 않습니다. 보낼 때마다 새 리소스가 생깁니다.PATCH: 스펙상 멱등성이 보장되지 않습니다.{ "name": "kim" }같은 patch는 멱등하지만,{ "op": "increment", "value": 1 }같은 patch는 보낼 때마다 값이 달라집니다.
이게 실무에서 중요한 이유는 재시도 안전성 때문입니다. 네트워크가 끊겨 응답을 못 받았을 때, 요청이 도달했는지 알 수 없습니다. 멱등한 메서드라면 그냥 다시 보내면 되지만, POST는 다시 보내면 결제나 주문이 두 번 생길 수 있습니다. 그래서 프록시나 HTTP 클라이언트는 보통 멱등한 메서드만 자동 재시도합니다.
POST를 안전하게 재시도해야 한다면 클라이언트가 요청마다 고유한 키를 만들어 헤더에 실어 보내고, 서버가 그 키를 기억해 같은 키의 두 번째 요청은 첫 결과를 그대로 돌려주는 방식을 씁니다. 결제 API들이 idempotency key를 요구하는 이유입니다.
GET 요청에 body를 넣어도 되나요?
HTTP spec 논의와 구현 차이가 있지만, 일반적인 API 설계에서는 GET body에 의존하지 않는 편이 안전합니다. query parameter로 조회 조건을 표현하는 경우가 많습니다.
캐시와 proxy 호환성도 고려해야 합니다.
RFC 9110은 GET에 본문을 붙이는 것을 금지하지는 않지만 정의된 의미가 없다고 못 박습니다. 서버가 그 본문을 무시해도 되고, 아예 거절해도 규격 위반이 아니라는 뜻입니다. 실제로 중간 프록시나 캐시가 본문을 떼어버리는 경우가 있고, 브라우저의 fetch는 GET이나 HEAD에 body를 넣으면 TypeError를 던집니다. 브라우저에서는 아예 선택지가 아닙니다.
캐시 문제도 있습니다. HTTP 캐시는 URL을 키로 삼기 때문에, 조회 조건이 본문에만 있으면 서로 다른 조회가 같은 캐시 항목으로 취급됩니다.
그래서 조회 조건이 복잡해 query string으로 감당이 안 될 때는 보통 두 가지 중 하나를 택합니다. 조건을 인코딩해 query parameter 하나에 담거나, POST /searches처럼 검색을 하나의 리소스 생성으로 모델링하는 방식입니다. 후자는 REST 원칙에서 벗어나 보이지만, 조건이 큰 검색에서는 널리 쓰이는 절충입니다.
status code는 왜 중요한가요?
client가 응답의 의미를 일관되게 처리할 수 있게 해줍니다. 예를 들어 인증 실패는 401, 권한 없음은 403, 없는 resource는 404처럼 구분할 수 있습니다.
모든 실패를 200으로 감싸면 HTTP layer의 의미를 잃게 됩니다.
200으로 감쌌을 때 잃는 것이 생각보다 넓습니다. 브라우저와 프록시의 캐시 동작, 모니터링 도구의 에러율 집계, HTTP 클라이언트의 자동 재시도, 프론트엔드에서 response.ok로 갈라지는 분기가 전부 무력화됩니다. 에러를 판별하려면 매번 본문을 파싱해야 하고, 그 규칙을 아는 코드만 이 API를 쓸 수 있게 됩니다.
반대 방향의 함정도 있습니다. 결과가 없는 것과 리소스가 없는 것은 다릅니다. GET /users?name=kim이 아무도 못 찾았다면 이건 성공한 요청이고 빈 배열을 담은 200이 맞습니다. 404는 /users/999처럼 특정 리소스를 지목했는데 그게 없을 때 씁니다. 목록 조회에 404를 주면 클라이언트가 '엔드포인트가 잘못됐나'와 '결과가 없나'를 구분하지 못합니다.
자주 헷갈리는 짝도 정리해두면 좋습니다.
401은 누구인지 모르겠다(인증 실패),403은 누구인지는 알지만 권한이 없다.400은 요청 형식 자체가 잘못됨,422는 형식은 맞는데 값이 규칙에 어긋남.201은 생성됨. 보통Location헤더에 만들어진 리소스의 URI를 담습니다.409는 현재 상태와 충돌. 중복 등록이나 동시 수정 충돌에 씁니다.
URI를 행위 중심으로 만들면 어떤 문제가 생기나요?
/getUser, /createPost처럼 URI가 행위 중심으로 늘어나면 HTTP method가 가진 의미가 약해집니다. 같은 조회나 변경도 endpoint마다 규칙이 달라져 client가 일관되게 이해하기 어렵습니다.
REST에 가깝게 설계하려면 URI는 resource를 가리키고, 행위는 GET, POST, PUT, PATCH, DELETE 같은 method로 표현하는 편이 자연스럽습니다.
어디까지 REST를 지켰는지를 단계로 나눈 것이 Richardson Maturity Model입니다. 자기 API가 어느 단계인지 말할 수 있으면 설명이 훨씬 명확해집니다.
- Level 0: 단일 엔드포인트에 모든 요청을
POST로 보냅니다. HTTP를 전송 수단으로만 씁니다. - Level 1: 리소스별로 URI를 나눕니다.
/users,/orders처럼 대상이 구분됩니다. - Level 2: HTTP 메서드와 상태 코드를 의미대로 씁니다. 실무의 대부분이 여기에 있고, 보통 이 정도를 RESTful이라고 부릅니다.
- Level 3: 응답에 다음에 할 수 있는 행동의 링크를 담습니다(HATEOAS). 주문 조회 응답에 취소 링크가 함께 오는 식입니다.
Level 3까지 가는 경우가 드문 이유는 비용 대비 효과가 잘 안 나오기 때문입니다. HATEOAS의 목표는 클라이언트가 URI를 하드코딩하지 않고 응답에 담긴 링크를 따라가게 만들어, 서버가 URI 구조를 바꿔도 클라이언트가 안 깨지게 하는 것입니다. 그런데 실제 클라이언트는 링크를 따라가도 어떤 필드를 어떻게 화면에 그릴지는 결국 하드코딩하므로 결합이 완전히 사라지지 않고, 응답 크기와 구현 복잡도만 늘어납니다.
행위가 리소스로 잘 안 떨어지는 경우도 있습니다. '비밀번호 재설정'이나 '주문 취소' 같은 것입니다. 이럴 때는 억지로 명사를 만들기보다, 그 행위를 하나의 리소스로 보고 POST /orders/{id}/cancellations처럼 표현하거나 POST /orders/{id}/cancel처럼 예외를 두고 문서에 명시하는 편이 실용적입니다. 일관성이 없는 것보다 예외를 명시적으로 두는 쪽이 낫습니다.
부가 설명
GET /users/1
POST /users
PATCH /users/1
DELETE /users/1/getUser, /createUser처럼 동사를 URL에 넣기보다, resource는 URL로 두고 행위는 method로 표현합니다.
REST는 엄밀한 architectural style이고, 실무에서 말하는 RESTful API는 그 원칙을 현실적으로 적용한 HTTP API를 뜻하는 경우가 많습니다. 완벽한 REST를 지키는지보다, resource 모델과 HTTP semantics를 일관되게 쓰는지가 더 중요할 때가 많습니다.
한 줄 정리
RESTful API는 URI로 resource를 표현하고 HTTP method와 status code로 행위와 결과를 일관되게 전달하는 설계 방식입니다.