2026年版 定期借家契約の解説

API 개발의 복잡성을 이해하고 효율적인 RESTful API 설계 원칙을 익혀보세요.

이 글에서는 RESTful API의 기본 개념부터 시작하여, 실제 API 설계 시 고려해야 할 중요한 원칙과 패턴들을 상세히 설명합니다. 아키텍처 스타일로서의 REST의 특징을 이해하고, 이를 바탕으로 확장 가능하고 유지보수하기 쉬운 API를 설계하는 방법을 배우게 될 것입니다.

목차

08실제 API 설계 사례

09마무리하며

RESTful API란 무엇인가?

RESTful API는 Representational State Transfer(REST) 아키텍처 스타일을 기반으로 하는 웹 서비스 인터페이스입니다. REST는 분산 시스템, 특히 인터넷과 같은 월드 와이드 웹(WWW)의 특성을 살리기 위한 설계 원칙들의 집합입니다. RESTful API는 HTTP 프로토콜의 표준 기능을 활용하여 클라이언트와 서버 간의 통신을 단순화하고, 상태 비저장(Stateless) 원칙을 통해 확장성과 신뢰성을 높입니다. 이는 웹 기반 애플리케이션, 모바일 앱, 그리고 다양한 서비스 간의 연동에서 사실상의 표준으로 자리 잡았습니다.

RESTful API는 다음과 같은 주요 제약 조건(Constraints)을 따릅니다:

1. 클라이언트-서버 (Client-Server)

클라이언트와 서버의 역할 분리가 명확해야 합니다. 클라이언트는 사용자 인터페이스와 사용자 경험에 집중하고, 서버는 데이터 저장, 비즈니스 로직, 보안 등에 집중합니다. 이러한 분리는 각 컴포넌트의 독립적인 발전을 가능하게 합니다.

2. 무상태 (Stateless)

서버는 클라이언트의 어떤 상태 정보도 저장하지 않습니다. 모든 요청은 클라이언트가 필요한 모든 정보를 포함해야 하며, 서버는 요청을 처리하고 응답만 반환합니다. 이는 서버의 확장성과 가용성을 높이는 데 매우 중요합니다. 예를 들어, 로그인 세션 정보는 클라이언트 측(예: 토큰)에서 관리해야 합니다.

3. 캐시 가능 (Cacheable)

서버 응답은 클라이언트에 의해 캐시될 수 있다는 것을 명시적으로 또는 암시적으로 표시해야 합니다. 이를 통해 클라이언트의 성능을 향상시키고 서버 부하를 줄일 수 있습니다. HTTP 헤더의 Cache-Control, Expires 등이 이 역할을 합니다.

4. 공통 인터페이스 (Uniform Interface)

RESTful API의 가장 중요한 제약 조건 중 하나입니다. 클라이언트와 서버 간의 상호작용을 단순화하고, 각 컴포넌트의 독립적인 발전을 가능하게 합니다. 공통 인터페이스는 다음 네 가지 하위 제약 조건으로 구성됩니다:

– 식별 가능한 리소스 (Identification of Resources): 모든 자원은 URI(Uniform Resource Identifier)를 통해 식별됩니다. 예를 들어, /users/123은 사용자 ID가 123인 특정 사용자를 나타냅니다.

– 리소스 조작을 위한 표현(Representation) 사용: 클라이언트는 리소스의 상태를 나타내는 표현(예: JSON, XML)을 받습니다. 클라이언트가 리소스를 수정하고자 할 때는, 수정하고자 하는 리소스의 표현을 서버로 전송합니다.

– 자기 서술적 메시지 (Self-descriptive Messages): 각 메시지는 수신자가 메시지를 이해하고 처리하는 데 필요한 모든 정보(예: 미디어 타입)를 포함해야 합니다. HTTP 헤더가 이 역할을 합니다.

– HATEOAS (Hypermedia as the Engine of Application State): 클라이언트는 서버로부터 받은 리소스 표현 내의 하이퍼미디어 링크를 통해 다음 상태로 이동하거나 관련 리소스에 접근할 수 있습니다. 즉, API가 어떻게 사용되어야 하는지에 대한 정보를 응답 자체에 포함시킵니다.

5. 계층화된 시스템 (Layered System)

클라이언트는 일반적으로 최종 서버와 직접 통신하는지, 아니면 중간 프록시 서버와 통신하는지 알 수 없습니다. 이는 시스템의 확장성을 용이하게 합니다. 로드 밸런서, 게이트웨이 등이 이 계층에 해당될 수 있습니다.

6. 코드 온 디맨드 (Code-On-Demand) – 선택 사항

서버는 클라이언트에게 실행 가능한 코드(예: JavaScript)를 전송하여 클라이언트의 기능을 확장할 수 있습니다. 이 제약 조건은 REST의 필수 조건은 아니며, 구현되지 않는 경우도 많습니다.

RESTful API 설계의 핵심 원칙

잘 설계된 RESTful API는 사용하기 쉽고, 예측 가능하며, 유지보수하기 용이합니다. 다음은 RESTful API를 설계할 때 반드시 고려해야 할 핵심 원칙들입니다.

1. 리소스 중심 설계 (Resource-Centric Design)

API는 명사(Nouns)를 기반으로 리소스를 정의해야 합니다. 동사(Verbs)는 HTTP 메서드를 통해 표현되어야 합니다. 예를 들어, /users는 사용자 리소스 컬렉션을, /users/{id}는 특정 사용자를 나타냅니다. GET /users/{id}는 특정 사용자를 조회하는 요청이 됩니다.

2. 일관된 URI 구조 (Consistent URI Structure)

URI는 명확하고 예측 가능해야 합니다. 계층 구조를 사용하여 리소스 간의 관계를 표현하는 것이 좋습니다. 예를 들어, 특정 사용자의 주문 목록을 조회하려면 /users/{userId}/orders와 같이 설계할 수 있습니다.

3. HTTP 메서드의 올바른 사용 (Proper Use of HTTP Methods)

HTTP 메서드(GET, POST, PUT, DELETE, PATCH 등)는 리소스에 대한 특정 작업을 나타내는 데 사용되어야 합니다. 각 메서드의 의미를 정확히 이해하고 적용하는 것이 중요합니다.

– GET: 리소스 조회. 안전하고 멱등적입니다. (반복 요청해도 결과가 동일)

– POST: 새 리소스 생성 또는 특정 작업 수행. 멱등적이지 않습니다.

– PUT: 리소스 전체 업데이트 또는 생성. 멱등적입니다.

– DELETE: 리소스 삭제. 멱등적입니다.

– PATCH: 리소스 부분 업데이트. 멱등적이지 않을 수 있습니다.

4. 상태 코드 활용 (Leverage Status Codes)

HTTP 상태 코드는 요청 처리 결과를 명확하게 전달하는 데 필수적입니다. 일반적인 상태 코드들은 다음과 같습니다:

– 2xx (Success): 200 OK, 201 Created, 204 No Content

– 3xx (Redirection): 301 Moved Permanently, 304 Not Modified

– 4xx (Client Error): 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict

– 5xx (Server Error): 500 Internal Server Error, 503 Service Unavailable

5. 명확한 응답 형식 (Clear Response Format)

일관되고 예측 가능한 응답 형식을 사용해야 합니다. JSON은 웹 API에서 가장 널리 사용되는 형식이며, 명확한 구조를 제공합니다. 응답 본문에는 요청 결과를 나타내는 데이터와 함께, 필요한 경우 오류 정보를 포함해야 합니다.

6. 필터링, 정렬, 페이징 지원 (Support Filtering, Sorting, Paging)

대규모 데이터셋을 다룰 때는 클라이언트가 원하는 데이터를 효율적으로 가져올 수 있도록 지원해야 합니다. 이는 주로 쿼리 파라미터를 통해 구현됩니다.

– 필터링: /products?category=electronics&inStock=true

– 정렬: /users?sortBy=lastName&sortOrder=asc

– 페이징: /items?page=2&pageSize=20 또는 /items?offset=20&limit=20

7. HATEOAS 적용 (Implementing HATEOAS)

앞서 언급했듯이, HATEOAS는 API의 자체 설명 능력을 높여 클라이언트가 API를 더 쉽게 탐색하고 사용할 수 있도록 합니다. 응답 본문에 관련 리소스나 다음 가능한 액션으로 연결되는 링크를 포함합니다.

예시:

{
  "orderId": 12345,
  "status": "shipped",
  "totalAmount": 75.50,
  "_links": {
    "self": { "href": "/orders/12345" },
    "customer": { "href": "/customers/987" },
    "cancel": { "href": "/orders/12345/cancel", "method": "POST", "description": "Cancel this order" }
  }
}

주요 RESTful API 설계 패턴

RESTful API 설계에는 다양한 패턴들이 있으며, 이러한 패턴들을 이해하고 적용하면 더욱 견고하고 효율적인 API를 만들 수 있습니다.

1. 리소스 명명 패턴 (Resource Naming Patterns)

URI는 일관성 있고 명확해야 합니다. 일반적으로 다음과 같은 패턴을 따릅니다.

– 컬렉션: /resource-name (예: /users, /products)

– 특정 리소스: /resource-name/{id} (예: /users/123, /products/abc)

– 하위 리소스: /resource-name/{id}/sub-resource (예: /users/123/orders)

– 컬렉션에 대한 작업: /resource-name/action (예: /users/search – GET 요청에 쿼리 파라미터 사용이 더 권장됨)

2. 에러 처리 패턴 (Error Handling Patterns)

API에서 발생하는 오류는 클라이언트에게 명확하게 전달되어야 합니다. HTTP 상태 코드와 함께, 응답 본문에 오류 메시지와 코드, 추가 정보를 포함하는 것이 좋습니다.

예시 (400 Bad Request):

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Email address is not valid.",
    "details": "The provided email 'test@' does not conform to standard email format."
  }
}

3. 데이터 페이징 패턴 (Data Paging Patterns)

대량의 데이터를 효율적으로 전달하기 위한 패턴입니다. 주로 limit/offset 또는 page/pageSize 방식을 사용합니다.

– Limit/Offset: /items?limit=10&offset=20 (20개 항목을 건너뛰고 다음 10개 항목 반환)

– Page/PageSize: /items?page=3&pageSize=10 (3번째 페이지, 각 페이지당 10개 항목)

응답 시에는 현재 페이지 정보, 총 페이지 수, 다음/이전 페이지 링크 등을 포함하는 것이 사용자 경험에 좋습니다.

4. 버전 관리 패턴 (Versioning Patterns)

API는 시간이 지남에 따라 변경될 수 있으며, 기존 클라이언트와의 호환성을 유지하기 위해 버전 관리가 필요합니다. 일반적인 방법은 다음과 같습니다.

– URI 버전 관리: /v1/users, /v2/users (가장 흔하고 직관적)

– 쿼리 파라미터 버전 관리: /users?version=1

– 헤더 버전 관리: Accept: application/vnd.company.v1+json 또는 사용자 정의 헤더 사용

5. 인증 및 인가 패턴 (Authentication & Authorization Patterns)

API 보안은 매우 중요합니다. 널리 사용되는 패턴으로는 API 키, OAuth 2.0, JWT(JSON Web Tokens) 등이 있습니다.

– API 키: 간단한 인증에 사용될 수 있으나, 보안 수준은 낮습니다.

– OAuth 2.0: 사용자 위임 권한 부여를 위한 표준 프로토콜. 소셜 로그인 등에 활용됩니다.

– JWT: 사용자의 인증 및 권한 정보를 안전하게 전달하기 위한 토큰 기반 인증 방식. 상태 비저장(Stateless) 특성과 잘 맞습니다.

HTTP 메서드 활용 전략

HTTP 메서드는 RESTful API의 핵심 요소이며, 각 메서드의 의미를 정확히 이해하고 적용하는 것이 API의 RESTful함을 결정짓습니다. 잘못된 메서드 사용은 API의 의도를 모호하게 만들고 클라이언트의 혼란을 야기할 수 있습니다.

1. GET: 리소스 조회

GET 메서드는 서버로부터 특정 리소스 또는 리소스 컬렉션을 조회하는 데 사용됩니다. GET 요청은 데이터를 변경해서는 안 되며(안전성, Safe), 여러 번 호출해도 동일한 결과를 반환해야 합니다(멱등성, Idempotent). 따라서 GET 요청에는 본문(body)을 포함하지 않으며, 필요한 파라미터는 쿼리 스트링을 통해 전달합니다.

예시:

GET /users/123 HTTP/1.1
Host: api.example.com
Accept: application/json

GET /products?category=electronics&limit=10 HTTP/1.1
Host: api.example.com
Accept: application/json

2. POST: 새 리소스 생성 또는 특정 작업 수행

POST 메서드는 주로 새 리소스를 생성하는 데 사용됩니다. 예를 들어, POST /users 요청은 새로운 사용자 리소스를 생성합니다. 또한, POST는 특정 리소스에 대해 정의되지 않은 작업을 수행하는 데에도 사용될 수 있습니다. 예를 들어, POST /orders/12345/cancel과 같이 리소스 자체를 삭제하는 것이 아니라 특정 상태로 변경하는 경우에 사용할 수 있습니다. POST 요청은 멱등적이지 않습니다.

예시:

POST /users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "[email protected]"
}

POST /orders/12345/cancel HTTP/1.1
Host: api.example.com

3. PUT: 리소스 전체 업데이트 또는 생성

PUT 메서드는 지정된 URI의 리소스를 전체적으로 업데이트하거나, 해당 URI에 리소스가 존재하지 않으면 생성하는 데 사용됩니다. PUT 요청은 멱등적입니다. 즉, 동일한 PUT 요청을 여러 번 반복해도 서버의 상태는 한 번만 변경된 것처럼 동일하게 유지됩니다. 요청 본문에는 업데이트될 리소스의 전체 표현이 포함되어야 합니다.

예시:

PUT /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe Updated",
  "email": "[email protected]",
  "age": 30
}

4. DELETE: 리소스 삭제

DELETE 메서드는 지정된 URI의 리소스를 삭제하는 데 사용됩니다. DELETE 요청 역시 멱등적입니다. 즉, 한 번 리소스를 삭제한 후 동일한 DELETE 요청을 반복해도 서버의 상태는 변경되지 않습니다(이미 삭제되었으므로). 성공 시 204 No Content 상태 코드를 반환하는 것이 일반적입니다.

예시:

DELETE /users/123 HTTP/1.1
Host: api.example.com

5. PATCH: 리소스 부분 업데이트

PATCH 메서드는 리소스의 일부만 수정하는 데 사용됩니다. PUT이 리소스 전체를 교체하는 것과 달리, PATCH는 지정된 필드만 변경합니다. 이는 네트워크 대역폭을 절약하고, 동시 수정 시 충돌 가능성을 줄이는 데 도움이 될 수 있습니다. PATCH 요청은 멱등적이지 않을 수 있습니다.

예시 (사용자 이름만 변경):

PATCH /users/123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "name": "Jane Doe Patched"
}

버전 관리 전략

API는 서비스의 성장과 함께 변화합니다. 클라이언트와의 호환성을 유지하면서 API를 발전시키는 것은 매우 중요하며, 이를 위해 버전 관리가 필수적입니다. 다양한 버전 관리 전략이 있으며, 각각 장단점을 가지고 있습니다.

1. URI 버전 관리 (URI Versioning)

이 방법은 API URI 자체에 버전을 포함하는 방식입니다. 가장 흔하고 직관적인 방법으로, 어떤 버전의 API를 호출하는지 명확하게 알 수 있습니다.

예시:

https://api.example.com/v1/users
https://api.example.com/v2/users

장점: 명확하고 이해하기 쉬움, 브라우저 캐싱 용이, SEO에 유리 (일부 경우).

단점: URI가 길어질 수 있음, 라우팅 설정이 복잡해질 수 있음.

2. 쿼리 파라미터 버전 관리 (Query Parameter Versioning)

URL의 쿼리 스트링에 버전을 포함시키는 방식입니다.

예시:

https://api.example.com/users?version=1
https://api.example.com/users?version=2

장점: URI가 깔끔하게 유지됨.

단점: 캐싱 문제가 발생할 수 있음 (동일한 URL이라도 쿼리 파라미터에 따라 다른 리소스가 반환될 수 있으므로 캐싱 로직이 복잡해짐), API의 의도가 덜 명확해질 수 있음.

3. 헤더 버전 관리 (Header Versioning)

HTTP 요청 헤더를 사용하여 버전을 지정하는 방식입니다. Accept 헤더를 사용하거나 사용자 정의 헤더를 사용할 수 있습니다.

예시 (Accept 헤더 사용):

Accept: application/vnd.example.v1+json
Accept: application/vnd.example.v2+json

예시 (사용자 정의 헤더):

X-API-Version: 1
X-API-Version: 2

장점: URI를 깔끔하게 유지할 수 있음, RESTful 원칙에 더 부합한다고 주장되기도 함.

단점: 클라이언트가 헤더 값을 직접 관리해야 하므로 복잡할 수 있음, 디버깅이 어려울 수 있음, 캐싱 문제가 발생할 수 있음.

4. 요청 본문 버전 관리 (Request Body Versioning)

요청 본문(body) 내부에 버전을 포함시키는 방식입니다. 주로 POST나 PUT 요청에서 사용됩니다.

예시:

{
  "version": 1,
  "data": { ... }
}

장점: 특정 요청에 대한 버전 명시.

단점: POST/PUT 요청에만 적용 가능, GET 요청 등에는 사용 불가, API의 의도가 불분명해질 수 있음, 가장 권장되지 않는 방식 중 하나.

권장 전략: URI 버전 관리

대부분의 경우, URI 버전 관리가 가장 명확하고 실용적인 선택입니다. 이는 API의 목적을 명확히 하고, 개발자와 클라이언트 모두에게 이해하기 쉬운 구조를 제공합니다. 예를 들어, /v1/users와 같이 URI에 명시적으로 버전을 포함시키는 것이 좋습니다.

보안 고려 사항

API 보안은 무결성, 기밀성, 가용성을 보장하는 데 매우 중요합니다. API를 설계하고 구현할 때 다음 보안 고려 사항들을 반드시 검토해야 합니다.

1. 인증 (Authentication)

API에 접근하는 사용자가 누구인지 확인하는 과정입니다. 클라이언트가 누구인지 증명해야 합니다.

– API 키: 단순하지만, 보안 수준이 낮아 기밀 정보 접근에는 부적합.

– 기본 인증 (Basic Auth): 사용자 이름과 비밀번호를 Base64로 인코딩하여 전송. HTTPS 필수.

– 토큰 기반 인증 (Token-based Auth): OAuth 2.0, JWT(JSON Web Tokens) 등이 널리 사용됩니다. 클라이언트가 로그인 후 받은 토큰을 API 요청 시 헤더에 포함하여 인증합니다. RESTful API의 무상태(Stateless) 원칙과 잘 맞습니다.

2. 인가 (Authorization)

인증된 사용자가 특정 리소스나 기능에 접근할 권한이 있는지 확인하는 과정입니다. “인증”은 ‘누구인가?’를 확인하는 것이고, “인가”는 ‘무엇을 할 수 있는가?’를 확인하는 것입니다.

– 역할 기반 접근 제어 (RBAC): 사용자에게 역할을 부여하고, 역할별로 접근 권한을 정의.

– 권한 기반 접근 제어 (ABAC): 특정 속성(사용자, 리소스, 환경 등)을 기반으로 접근 권한을 동적으로 결정.

API 게이트웨이나 미들웨어를 사용하여 인가 로직을 중앙에서 관리할 수 있습니다.

3. HTTPS 사용

모든 API 통신은 반드시 HTTPS(SSL/TLS)를 사용해야 합니다. 이는 데이터 전송 중 암호화를 통해 기밀성을 보장하고, 통신 상대방이 진짜 서버인지 확인(인증)하여 중간자 공격(Man-in-the-Middle Attack)을 방지합니다.

4. 입력값 검증 (Input Validation)

클라이언트로부터 받은 모든 입력값은 서버 측에서 철저히 검증해야 합니다. 이는 SQL Injection, Cross-Site Scripting (XSS) 등의 공격을 방지하고, 예상치 못한 데이터로 인한 시스템 오류를 막는 데 중요합니다.

– 데이터 타입, 길이, 형식, 범위 등을 검증합니다.

– 허용된 문자 집합만 사용하도록 제한합니다.

5. 속도 제한 (Rate Limiting)

악의적인 공격이나 과도한 사용으로 인해 서버가 과부하되는 것을 방지하기 위해, 특정 시간 동안 클라이언트가 API를 호출할 수 있는 횟수를 제한해야 합니다. IP 주소, 사용자 ID, API 키 등을 기준으로 제한할 수 있습니다.

6. 민감 정보 노출 방지

API 응답에는 불필요한 민감 정보(예: 비밀번호 해시, 내부 시스템 정보 등)가 포함되지 않도록 주의해야 합니다. 200 OK 응답에도 의도치 않은 정보가 포함될 수 있으므로, 응답 데이터를 항상 검토해야 합니다.

API 문서화의 중요성

잘 작성된 API 문서는 API의 성공에 매우 중요한 역할을 합니다. 이는 API 사용자가 API를 이해하고 효과적으로 활용하는 데 필수적인 가이드 역할을 합니다.

1. API 사용 편의성 증대

명확한 문서는 개발자가 API의 엔드포인트, 요청/응답 형식, 사용 가능한 파라미터, 인증 방법 등을 쉽게 파악할 수 있도록 돕습니다. 이는 API 학습 곡선을 낮추고 개발 시간을 단축시킵니다.

2. 오류 감소 및 지원 비용 절감

잘 문서화된 API는 사용자의 오해나 잘못된 사용으로 인한 오류를 줄여줍니다. 이는 고객 지원팀이 받는 문의를 감소시켜 운영 비용을 절감하는 효과로 이어집니다.

3. API 유지보수 및 진화 용이

API가 변경되거나 업데이트될 때, 문서를 최신 상태로 유지하면 기존 사용자들이 변경 사항을 쉽게 인지하고 적응할 수 있습니다. 이는 API의 안정적인 운영과 발전에 기여합니다.

4. 표준 문서화 도구 활용

API 문서를 작성하는 데는 여러 표준 도구가 있습니다.

– Swagger/OpenAPI Specification: RESTful API를 위한 표준 인터페이스 설명으로, API 설계, 문서화, 테스트, 코드 생성 등 전반에 걸쳐 활용됩니다. YAML 또는 JSON 형식으로 API 명세를 정의합니다.

– RAML (RESTful API Modeling Language): API를 모델링하고 문서화하기 위한 언어.

– API Blueprint: Markdown 기반의 API 설계 및 문서화 언어.

5. 문서화 내용 포함 사항