좋은 API란 무엇인가? REST API 설계 원칙과 성숙도 모델 완벽 가이드

 

1. 서론: 왜 모두가 'REST'를 외칠까?

현대 소프트웨어 아키텍처는 수많은 서비스가 서로 데이터를 주고받으며 작동합니다. 이때 서로 다른 환경(언어, 프레임워크)에서도 막힘없이 대화하기 위한 약속이 필요한데, 그중 가장 널리 쓰이는 표준이 바로 **REST(Representational State Transfer)**입니다. 하지만 단순히 HTTP를 쓴다고 해서 모두 RESTful한 것은 아닙니다. 오늘은 진정한 의미의 REST API가 무엇인지, 그리고 어떻게 설계해야 하는지 깊이 있게 알아보겠습니다.

2. REST API의 6가지 기본 원칙

REST 아키텍처를 유지하기 위해서는 다음의 제약 조건을 준수해야 합니다.

  1. Client-Server 구조: 서버와 클라이언트의 역할을 명확히 분리하여 독립적인 진화를 가능하게 합니다.

  2. Stateless (무상태성): 서버는 클라이언트의 상태를 기억하지 않습니다. 각 요청은 처리에 필요한 모든 정보를 포함해야 합니다.

  3. Cacheable (캐시 가능): HTTP의 기존 웹 표준을 그대로 활용하여 응답을 캐싱할 수 있어야 합니다.

  4. Uniform Interface (일관된 인터페이스): 리소스(URL)와 행위(HTTP Method)가 표준화되어야 합니다.

  5. Layered System (계층화 시스템): 클라이언트는 서버가 직접 연결되었는지, 중간 매개체(로드밸런서 등)를 거쳤는지 알 수 없어야 합니다.

  6. Code on Demand (선택 사항): 서버가 클라이언트에 실행 가능한 코드를 전달할 수 있습니다.

3. 핵심 설계 가이드: 리소스와 행위의 분리

가장 많은 개발자가 실수하는 부분이 URL 설계입니다.

  • Bad: GET /get_user_info/123, POST /delete_post (행위를 URL에 포함)

  • Good: GET /users/123, DELETE /posts/45 (명사 위주의 리소스와 HTTP 메서드 조합)

HTTP Method역할 (CRUD)의미
GETRead리소스 조회
POSTCreate새 리소스 생성
PUTUpdate리소스 전체 수정
PATCHUpdate리소스 일부 수정
DELETEDelete리소스 삭제

4. 리처드슨 성숙도 모델 (Richardson Maturity Model)

단순한 HTTP 통신에서 진정한 REST로 나아가는 단계를 4단계로 구분합니다.

  • Level 0: 단일 엔드포인트에서 모든 요청 처리 (예: SOAP)

  • Level 1: 개별 리소스에 대한 URL 도입

  • Level 2: HTTP 메서드(GET, POST 등)의 적절한 활용

  • Level 3: HATEOAS 도입 (응답에 다음 단계로 갈 수 있는 링크 포함)

5. 실무 경험 사례: "모두가 고통받았던 나의 첫 번째 API 설계"

[나의 개발 경험: 무분별한 POST 사용이 부른 API 지옥]

신입 시절, 저는 모든 API를 POST 메서드로 통일해서 만든 적이 있었습니다. "보안상 안전하고 데이터 전송 용량 제한도 없으니 가장 좋은 게 아닐까?"라는 안일한 생각 때문이었죠.

하지만 프로젝트가 커지자 재앙이 시작되었습니다. 모든 요청이 POST이다 보니 브라우저나 프록시 서버의 캐싱 기능을 전혀 활용할 수 없었습니다. 또한, 동료 프론트엔드 개발자들은 API 문서(Swagger)를 봐도 이 API가 데이터를 가져오는 건지, 삭제하는 건지 직관적으로 알 수 없어 매번 저에게 물어봐야 했습니다.

결국 저는 모든 엔드포인트를 리소스 중심으로 재설계하고 적절한 HTTP 메서드를 적용하는 '대수술'을 진행했습니다. 이 과정을 통해 **'표준을 지키는 것이 가장 효율적인 소통 방법'**이라는 점을 절실히 깨달았습니다.

6. 결론: RESTful은 정답이 아닌 '철학'입니다

REST API를 완벽하게 구현하는 것은 생각보다 까다롭습니다. 특히 레벨 3의 HATEOAS까지 지키는 곳은 실무에서도 드뭅니다. 중요한 것은 내 API를 사용하는 사람(혹은 기계)이 얼마나 직관적이고 편하게 소통할 수 있느냐입니다. 오늘 정리한 원칙들을 바탕으로 더 건강하고 아름다운 API를 설계해 보시길 바랍니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

빵집 줄서기와 시간 복잡도의 관계

  빵집 줄서기와 시간 복잡도의 관계 알고리즘을 공부하다 보면 반드시 등장하는 개념이 있습니다. 바로 시간 복잡도(Time Complexity)입니다. 많은 초보자들이 이 용어를 듣고 어려워하지만, 사실 시간 복잡도는 우리 일상 속에서도 자연스럽게 경험할 수 있는 개념입니다. 가장 쉬운 예시가 바로 빵집 줄서기입니다. 빵집 앞에 사람들이 길게 줄을 서 있을 때, 빵을 사는 데 걸리는 시간을 계산하는 원리를 이해하면 시간 복잡도가 왜 중요한지 바로 감이 잡힙니다. 1. 시간 복잡도란 무엇인가 시간 복잡도는 간단히 말해 프로그램이 데이터를 처리하는 데 걸리는 시간의 변화량을 나타내는 개념입니다. 즉, 데이터가 많아질수록 프로그램이 얼마나 느려지는지를 예측하는 기준이라고 볼 수 있습니다. 예를 들어 10개의 데이터를 처리하는 프로그램이 있다면, 그걸 100개, 1000개로 늘렸을 때 실행 시간이 얼마나 늘어나는지를 계산하는 것이 시간 복잡도의 핵심입니다. 시간 복잡도는 보통 O(빅오) 표기법으로 표현합니다. 예를 들어 O(1), O(n), O(n²), O(log n) 같은 형태가 대표적입니다. 이 표기는 “데이터 개수 n이 커질수록 실행 시간이 어떤 비율로 증가하는가”를 수학적으로 나타낸 것입니다. 2. 빵집 줄서기와 시간 복잡도의 공통점 빵집에 손님이 한 명만 있을 때는 금방 계산이 끝납니다. 하지만 줄이 길어질수록 기다리는 시간은 점점 늘어나죠. 이 현상이 바로 시간 복잡도와 같습니다. 예를 들어 빵을 고르고 계산하는 데 각각 1분이 걸린다고 해봅시다. 손님이 한 명이면 2분이면 끝나지만, 손님이 10명이면 20분, 100명이면 200분이 걸립니다. 이런 관계는 O(n) 형태의 시간 복잡도라고 할 수 있습니다. 즉, 손님의 수가 n배로 늘어나면, 걸리는 시간도 n배로 증가합니다. 3. 효율이 떨어지는 줄서기 – O(n²) 구조 만약 빵집 직원이 손님을 효율적으로 처리...
자세한 내용 보기

변수와 상수의 차이, 그리고 실무에서의 활용 방법

  프로그래밍을 배우다 보면 가장 먼저 접하게 되는 개념이 ‘변수’와 ‘상수’다. 처음에는 두 단어가 비슷해 보여서 구분이 어려울 수 있다. 하지만 프로그램의 안정성과 효율성을 좌우하는 중요한 기초 개념이 바로 이 두 가지다. 변수와 상수를 정확히 이해하고 사용하는 습관은 초보 개발자와 숙련된 개발자를 가르는 분기점이 된다. 변수란 무엇인가 변수는 이름 그대로 ‘변할 수 있는 수’를 의미한다. 프로그램이 실행되는 동안 데이터가 계속 바뀔 수 있을 때 사용하는 저장공간이다. 예를 들어 로그인한 사용자의 이름, 장바구니의 총액, 게임 속 점수처럼 상황에 따라 계속 변하는 값들은 변수로 저장된다. 변수는 프로그램의 흐름을 따라 변화하며, 사용자 입력이나 계산 결과를 임시로 담는 역할을 한다. 파이썬을 예로 들어보면 다음과 같다. name = "민수" score = 90 이 코드는 name과 score라는 이름의 변수에 각각 문자열과 숫자 데이터를 담는 예다. 이후 score = score + 10 이라는 연산을 하면, score의 값이 100으로 바뀌게 된다. 바로 이런 변화 가능성이 변수의 핵심이다. 변수를 활용하면 프로그램이 상황에 맞게 유연하게 작동할 수 있다. 데이터를 즉시 수정하거나 새로운 값을 반영할 수 있기 때문이다. 하지만 이러한 유연성이 때로는 문제를 일으키기도 한다. 변수 값이 의도치 않게 바뀌면 전체 프로그램의 동작이 흔들릴 수 있기 때문이다. 그래서 언제 변수를 사용하고 언제 상수를 사용해야 하는지 판단하는 것이 중요하다. 상수란 무엇인가 상수는 ‘항상 같은 수’라는 뜻이다. 프로그램이 실행되는 동안 절대 변하지 않는 값을 저장한다. 예를 들어 원주율, 부가가치세율, 기본 할인율 등은 코드 전반에서 반복적으로 사용되지만, 절대로 바뀌지 않아야 한다. 이런 값은 상수로 선언하는 것이 안전하다. 파이썬에서는 상수를 명시적으로 지원하지 않지만, 관례적으로 대문자로 선언해 개발자가 변경하지 말아야 함을 표현한다...
자세한 내용 보기

파이썬 객체지향 프로그래밍(OOP) 완전정복 | 클래스, 상속, 캡슐화까지 한 번에 이해하기

  파이썬을 처음 배울 때는 변수와 함수만으로 프로그램을 구성하지만, 실무나 프로젝트 규모가 커질수록 코드 관리가 점점 어려워진다. 이때 필요한 개념이 바로 객체지향 프로그래밍이다. 객체지향 프로그래밍(OOP, Object Oriented Programming)은 프로그램을 단순한 명령어의 나열이 아닌 ‘객체’ 중심으로 바라보는 사고방식이다. 객체란 데이터와 기능을 하나로 묶은 단위이며, 현실 세계의 사물이나 개념을 코드로 표현한 것이다. 객체지향의 핵심은 크게 세 가지로 정리된다. 첫째, 캡슐화. 관련된 데이터와 기능을 하나의 객체로 묶어 외부 접근을 제한하는 개념이다. 둘째, 상속. 기존 코드를 재사용하면서 새로운 기능을 확장할 수 있도록 하는 기능이다. 셋째, 다형성. 같은 이름의 메서드가 객체에 따라 다른 동작을 하는 성질을 말한다. 이 세 가지 개념을 이해하면 코드를 효율적이고 유지보수하기 쉬운 구조로 만들 수 있다. 클래스와 객체의 기본 개념 클래스(Class)는 설계도이고, 객체(Object)는 그 설계도로부터 만들어진 실제 제품이라고 할 수 있다. 예를 들어 자동차 설계도가 클래스라면, 실제 우리가 타는 자동차는 객체다. 아래는 간단한 예시이다. Car라는 클래스를 만들고, 브랜드와 색상을 초기화한다. 그런 다음 drive 메서드를 통해 자동차가 출발하는 동작을 표현한다. 예시 코드 설명 class Car: 클래스를 선언한다. def init(self, brand, color): 생성자 함수로 브랜드와 색상을 초기화한다. def drive(self): 자동차가 출발했다는 문장을 출력한다. my_car = Car(“Hyundai”, “black”) 으로 객체를 생성한다. my_car.drive() 를 호출하면 “black색 Hyundai 자동차가 출발합니다!” 라는 문장이 출력된다. 이처럼 클래스는 관련된 데이터와 행동을 하나로 묶어 표현한다. 캡슐화(Encapsulation) ...
자세한 내용 보기