API와 계약

현대 소프트웨어 시스템에서 애플리케이션은 백엔드 로직과 직접 상호작용하는 경우가 거의 없습니다. 대신 API를 통해 통신하며, API는 시스템으로 들어가는 제어된 진입점 역할을 합니다.

브라우저, 모바일 애플리케이션 또는 다른 백엔드 서비스와 같은 클라이언트는 특정 API 엔드포인트로 요청을 보냅니다. API는 그 요청을 받아 포함된 정보를 해석한 뒤, 이를 적절한 백엔드 로직으로 전달합니다. 그런 다음 백엔드는 데이터베이스에서 데이터를 가져오거나 애플리케이션 규칙을 실행하는 등의 필요한 작업을 수행하고, 그 결과를 클라이언트에게 응답으로 반환합니다.

이러한 구조화된 통신 덕분에 시스템은 모듈식으로 유지될 수 있습니다. 프론트엔드 애플리케이션, 모바일 앱, 외부 서비스는 API가 정의한 요청 및 응답 형식을 따르기만 하면 동일한 백엔드 기능과 상호작용할 수 있습니다.

API는 요청이 어떤 구조여야 하는지와 응답이 어떤 모습이어야 하는지를 정의하므로, 시스템의 서로 다른 부분 사이에 예측 가능한 인터페이스를 만듭니다. 이 인터페이스를 통해 독립적으로 개발된 구성 요소들은 내부 백엔드 구현이 어떻게 동작하는지 알 필요 없이 안정적으로 통신할 수 있습니다.

클라이언트가 API 엔드포인트로 요청을 보낼 때는 어떤 종류의 작업을 수행하려는지 지정해야 합니다. 이 작업은 HTTP 메서드를 사용해 표현됩니다.

HTTP 메서드는 엔드포인트 URL과 함께 요청의 의미를 정의합니다.

예를 들어, GET /users 같은 요청은 서버에 사용자 데이터를 가져오라고 요청합니다. POST /users 같은 요청은 서버에 새 사용자를 생성하라고 요청합니다. DELETE /users/42 같은 요청은 백엔드에 특정 사용자를 삭제하라고 지시합니다.

API에서는 여러 HTTP 메서드가 일반적으로 사용됩니다.

GET은 서버에서 기존 데이터를 조회합니다.
POST는 새 리소스를 생성합니다.
PUT은 기존 리소스를 새 데이터로 대체합니다.
PATCH는 기존 리소스의 일부를 업데이트합니다.
DELETE는 시스템에서 리소스를 제거합니다.

엔드포인트와 HTTP 메서드를 함께 사용하면, API는 클라이언트가 시스템 리소스에 대해 수행할 수 있는 작업을 명확하게 정의합니다.

API 설계에서는 각 URL이 시스템이 무엇을 해야 하는지를 설명하는 작업 중심으로 엔드포인트를 구성하는 방법이 있습니다. 예를 들어, POST /createUser 같은 엔드포인트는 작업을 URL에 직접 인코딩합니다.

이 방식은 작은 시스템에서는 잘 작동하지만, 기능 수가 늘어나면 유지 관리가 어려워집니다. 엔드포인트가 일관되지 않게 되고, 새로운 기능이 어떻게 노출될지 예측하기도 더 어려워집니다.

REST는 사용자, 주문, 제품과 같은 리소스를 중심으로 API를 구성하는 다른 접근 방식을 사용합니다. URL에 작업을 인코딩하는 대신, 엔드포인트는 리소스를 나타내고 HTTP 메서드가 작업을 정의합니다.

예를 들어, POST /users는 새 사용자를 생성하고, GET /users는 사용자를 조회합니다. 이러한 분리는 전체 API에 걸쳐 일관된 패턴을 만듭니다.

이러한 구조 덕분에 RESTful API는 이해하기 쉽고, 확장하기 쉬우며, 기능을 추가하기도 쉽습니다. 개발자는 새 엔드포인트도 같은 예측 가능한 설계를 따르기 때문에 더 쉽게 다룰 수 있습니다.

REST는 시스템이 커져도 API가 일관되고 신뢰할 수 있게 유지되도록 돕는 일련의 설계 원칙 위에 구축됩니다.

중요한 원칙 중 하나는 상태 비저장 통신입니다. 각 요청에는 서버가 이를 처리하는 데 필요한 모든 정보가 포함되어야 합니다. 서버는 이전 요청에 의존하지 않으므로, 시스템을 더 쉽게 확장하고 분산할 수 있습니다.

또 다른 원칙은 리소스 기반 설계입니다. API는 사용자나 주문과 같은 엔티티를 리소스로 표현하며, 이러한 리소스는 /users 또는 /orders와 같은 URL로 식별됩니다.

REST는 표준 HTTP 의미 체계에도 의존합니다. GET, POST, PUT, PATCH, DELETE와 같은 HTTP 메서드는 리소스에 대해 수행되는 작업을 명확하게 표현하는 데 사용됩니다.

마지막으로, REST는 통일된 인터페이스를 강제합니다. 엔드포인트는 일관된 패턴을 따르므로 API를 이해하기 쉬워지고, 시스템의 다른 부분과 상호작용할 때 혼란이 줄어듭니다.

서버가 요청을 처리할 때, 그 결과를 클라이언트에 전달해야 합니다. HTTP 상태 코드는 그 결과를 설명하는 표준화된 방법을 제공합니다.

상태 코드는 범주별로 나뉩니다. 2xx 범위의 코드는 성공을 의미하며, 요청이 올바르게 처리되었음을 나타냅니다. 4xx 범위의 코드는 잘못된 입력이나 누락된 리소스와 같은 클라이언트 오류를 나타냅니다. 5xx 범위의 코드는 서버 오류를 나타내며, 백엔드에서 문제가 발생했음을 의미합니다.

대표적인 예로는 성공적인 요청을 나타내는 200 OK와, 새 리소스가 생성되었음을 확인하는 201 Created가 있습니다. 400 Bad Request 같은 오류는 잘못된 입력을 나타내고, 401 Unauthorized는 인증 정보가 없거나 유효하지 않음을 의미합니다. 404 Not Found 응답은 요청한 리소스가 존재하지 않음을 뜻하며, 500 Internal Server Error는 서버에서 실패가 발생했음을 나타냅니다.

클라이언트는 이러한 상태 코드를 사용해 다음에 어떻게 진행할지 결정합니다. 예를 들어, 서버 오류가 발생한 뒤 요청을 다시 시도하거나, 클라이언트 오류가 발생한 뒤 사용자에게 입력을 수정하라고 안내할 수 있습니다.

분산 시스템에서는 요청이 실패하거나, 타임아웃되거나, 여러 번 재시도될 수 있습니다. 따라서 백엔드 시스템은 반복된 요청을 안전하게 처리하도록 설계되어야 합니다.

같은 요청을 여러 번 보내도 최종 상태가 동일하면 그 작업은 멱등적이라고 봅니다. 예를 들어 DELETE /users/10을 한 번 호출하면 사용자가 삭제됩니다. 다시 호출해도 사용자는 이미 삭제된 상태이므로 더 이상 아무 변화도 일어나지 않습니다.

마찬가지로 PUT /users/10은 매번 같은 데이터로 리소스를 대체하므로, 요청을 반복해도 추가적인 부작용이 생기지 않습니다.

반면 POST /orders는 일반적으로 멱등적이지 않습니다. 각 요청이 새로운 주문을 생성하기 때문입니다. 같은 요청을 반복하면 중복된 리소스가 만들어질 수 있습니다.

멱등성은 시스템이 장애가 발생했을 때 요청을 자동으로 재시도하는 경우가 많기 때문에 중요합니다. 멱등성이 없으면 재시도로 인해 데이터 불일치, 중복 작업, 또는 의도하지 않은 부작용이 발생할 수 있습니다.

백엔드 시스템이 발전함에 따라 API도 자주 변경되어야 합니다. 새로운 기능이 추가되거나, 데이터 형식이 업데이트되거나, 기존 동작이 수정될 수 있습니다.

문제는 웹 앱, 모바일 앱, 서드파티 통합 같은 클라이언트가 기존 API 동작에 의존한다는 점입니다. API가 예고 없이 변경되면 이러한 클라이언트가 깨질 수 있습니다.

API 버전 관리는 하나의 API가 동시에 여러 버전으로 존재할 수 있게 해서 이 문제를 해결합니다. 기존 클라이언트는 원래 버전을 계속 사용할 수 있고, 새로운 클라이언트는 업데이트된 버전을 채택할 수 있습니다.

가장 흔한 방법 중 하나는 URL 버전 관리로, 버전을 경로에 포함하는 방식입니다. 예를 들어 /v1/users와 /v2/users처럼 사용합니다. 또 다른 방법은 헤더 버전 관리로, 클라이언트가 Accept: application/vnd.api.v2 같은 헤더를 사용해 버전을 지정하는 방식입니다.

API를 버전 관리하면 기존 클라이언트와의 호환성을 유지하면서 백엔드 시스템을 안전하게 발전시킬 수 있습니다.

API 계약은 클라이언트와 백엔드 시스템 사이의 합의처럼 작동합니다. 양쪽이 모호함 없이 상호작용할 수 있도록, 통신이 정확히 어떻게 이루어져야 하는지 정의합니다.

클라이언트가 HTTP 요청을 보낼 때는 올바른 엔드포인트를 사용하고, 예상되는 데이터 형식을 제공하며, 필요한 모든 정보를 포함하여 계약을 따라야 합니다. 백엔드 시스템은 이 규칙에 따라 요청을 처리하고 구조화된 HTTP 응답을 반환합니다.

계약은 사용 가능한 엔드포인트, 요청 데이터의 형식, 응답의 구조, 상태 코드의 의미, 각 작업의 예상 동작 등 API의 여러 중요한 측면을 정의합니다.

이 계약 덕분에 클라이언트는 백엔드가 내부적으로 어떻게 구현되었는지 이해할 필요가 없습니다. 정의된 인터페이스를 따르기만 하면 통신은 일관되고 신뢰할 수 있게 유지됩니다.

실무에서 API 계약은 프론트엔드와 백엔드 팀 간의 협업뿐만 아니라 독립적인 시스템 간 통합에도 필수적입니다.