API 레퍼런스

HTTP 메서드는 클라이언트가 서버에 특정 작업을 수행하도록 지시하는 동사를 의미한다. 이는 RESTful API 설계의 핵심 요소로, 리소스에 대해 수행할 연산의 종류를 명확히 정의한다. 가장 일반적으로 사용되는 메서드로는 데이터를 가져오는 GET, 새로운 리소스를 생성하는 POST, 기존 리소스를 완전히 교체하는 PUT, 리소스의 일부를 수정하는 PATCH, 그리고 리소스를 삭제하는 DELETE가 있다.

이 외에도 서버의 지원 여부에 따라 사용 가능한 다른 메서드들이 존재한다. 예를 들어, HEAD 메서드는 GET 요청과 동일하지만 응답 본문 없이 헤더 정보만 반환받는다. OPTIONS 메서드는 특정 엔드포인트에서 사용 가능한 HTTP 메서드 목록을 확인하는 데 사용된다. 또한 CONNECT나 TRACE와 같은 메서드는 주로 프록시 서버 디버깅 등 특수한 목적을 위해 정의되어 있다.

각 HTTP 메서드는 멱등성과 안전성이라는 특성을 가진다. 멱등성이란 동일한 요청을 여러 번 보내도 한 번 보낸 것과 같은 효과를 보장하는 성질을 말하며, GET, PUT, DELETE 메서드가 이에 해당한다. 안전성은 서버의 리소스 상태를 변경하지 않는 메서드의 특성으로, GET과 HEAD, OPTIONS가 대표적이다. 이러한 특성은 API의 신뢰성과 예측 가능성을 높이는 데 기여한다.

API 요청 시 클라이언트는 서버에 추가적인 메타데이터를 전달하기 위해 요청 헤더를 사용한다. 이 헤더들은 HTTP 프로토콜의 일부로, 요청의 성격, 클라이언트 정보, 인증 데이터, 그리고 서버가 응답을 어떻게 처리해야 하는지에 대한 지시사항을 포함한다.

주요 요청 헤더로는 인증을 위한 Authorization, 요청 본문의 형식을 나타내는 Content-Type, 클라이언트의 소프트웨어 정보를 알리는 User-Agent, 그리고 서버가 어떤 응답 형식을 선호하는지 지정하는 Accept 헤더 등이 있다. 또한, 캐시 제어를 위한 Cache-Control 헤더나 특정 조건부 요청을 위한 If-Modified-Since 헤더와 같은 기능성 헤더도 중요하게 사용된다.

올바른 헤더 설정은 API 호출의 성공과 효율성을 보장한다. 예를 들어, Content-Type 헤더를 application/json으로 설정하지 않으면 서버가 JSON 형식의 데이터를 올바르게 해석하지 못할 수 있다. 마찬가지로, OAuth나 API 키를 사용하는 경우 Authorization 헤더는 필수적으로 포함되어야 한다.

요청 본문은 클라이언트가 서버로 전송하는 데이터의 본체를 담는 부분이다. HTTP 요청에서 헤더 이후에 위치하며, 주로 POST, PUT, PATCH와 같은 메서드를 사용하여 리소스를 생성하거나 수정할 때 활용된다. 본문의 형식은 콘텐츠 타입 헤더로 명시되며, JSON이 현대 웹 API에서 가장 널리 사용되는 데이터 교환 형식이다. XML이나 폼 데이터 또한 특정 상황에서 요청 본문의 형식으로 사용될 수 있다.

요청 본문의 구조와 필드들은 API 설계 시 정의된 스키마를 따라야 한다. 이는 서버가 데이터를 올바르게 해석하고 처리하는 데 필수적이다. 예를 들어, 사용자 생성 API를 호출할 때 요청 본문에는 name, email과 같은 필수 필드가 정의된 형식으로 포함되어야 한다. 많은 API는 요청 본문 데이터의 유효성을 검사하기 위해 JSON 스키마나 유사한 검증 도구를 사용한다.

개발자는 API 레퍼런스나 문서화를 참조하여 각 엔드포인트별로 필요한 요청 본문의 정확한 형식, 필수 및 선택적 파라미터, 데이터 타입을 확인해야 한다. 잘못된 형식의 본문을 전송하면 서버는 400 Bad Request와 같은 상태 코드로 응답하며, 대개 응답 본문에 구체적인 오류 정보를 포함시켜 문제를 해결할 수 있도록 돕는다.

쿼리 파라미터는 URL의 끝부분에 ? 기호로 시작하여 추가되는 키-값 쌍의 데이터이다. 주로 GET 요청에서 서버에 특정 조건이나 옵션을 전달하는 데 사용되며, 여러 개의 파라미터는 & 기호로 연결한다. 예를 들어, 검색 결과를 페이지별로 조회하거나 특정 기준으로 정렬할 때 활용된다.

쿼리 파라미터의 구조는 키=값 형태를 기본으로 한다. 키는 파라미터의 이름을, 값은 해당 파라미터에 설정할 실제 데이터를 나타낸다. 값에는 공백이나 특수 문자가 포함될 경우 퍼센트 인코딩을 통해 안전하게 변환되어 전송되어야 한다. 이는 HTTP 프로토콜에서 URL의 표준 형식을 준수하기 위함이다.

REST API 설계에서 쿼리 파라미터는 리소스의 필터링, 정렬, 페이징, 검색과 같은 선택적 작업을 지정하는 데 주로 활용된다. 반면, 리소스의 고유 식별자는 일반적으로 URL 경로(path)에 포함시킨다. 이러한 관행은 API의 일관성과 가독성을 높이는 데 기여한다.

쿼리 파라미터를 설계할 때는 파라미터 키의 이름을 직관적으로 정하고, 문서화를 통해 각 파라미터의 용도와 허용되는 값의 형식을 명확히 설명해야 한다. 또한, 서버 측에서는 클라이언트로부터 전달받은 파라미터 값에 대한 유효성 검증을 철저히 수행하여 보안과 데이터 무결성을 유지하는 것이 중요하다.

API 호출에 대한 서버의 처리 결과를 나타내는 핵심 지표이다. HTTP 상태 코드는 세 자리 숫자로 구성되며, 첫 번째 숫자에 따라 응답의 범주가 결정된다. 이는 클라이언트가 요청의 성공 여부와 실패 원인을 신속하게 파악할 수 있도록 돕는다.

주요 상태 코드는 1xx(정보), 2xx(성공), 3xx(리다이렉션), 4xx(클라이언트 오류), 5xx(서버 오류)로 구분된다. 가장 일반적으로 사용되는 코드로는 요청 성공을 의미하는 200 OK, 잘못된 요청을 나타내는 400 Bad Request, 인증 실패 시 반환되는 401 Unauthorized, 접근 권한이 없음을 알리는 403 Forbidden, 요청한 리소스를 찾을 수 없을 때의 404 Not Found, 그리고 서버 내부 오류를 의미하는 500 Internal Server Error 등이 있다.

API 설계 시에는 각 엔드포인트가 발생시킬 수 있는 예외 상황에 대해 적절한 상태 코드를 정의하고 일관되게 반환하는 것이 중요하다. 또한, 오류 응답의 응답 본문에는 상태 코드만으로는 부족한 추가적인 오류 정보를 JSON 등의 형식으로 포함시켜 클라이언트의 디버깅을 지원해야 한다. 이를 통해 소프트웨어 개발 과정에서의 통합 및 문제 해결 효율성을 높일 수 있다.

응답 헤더는 서버가 클라이언트에게 반환하는 HTTP 응답의 일부로, 응답에 대한 부가적인 정보를 담고 있다. 이 정보에는 응답의 콘텐츠 타입, 캐시 제어 지시, 보안 관련 정책, 서버 정보 등이 포함된다. 응답 헤더는 클라이언트가 서버로부터 받은 데이터를 올바르게 해석하고 처리하는 데 필수적인 역할을 한다.

일반적으로 자주 사용되는 응답 헤더로는 Content-Type, Cache-Control, Access-Control-Allow-Origin 등이 있다. Content-Type 헤더는 응답 본문의 미디어 타입을 명시하며, 예를 들어 application/json이나 text/html과 같은 값을 가진다. Cache-Control 헤더는 응답 데이터를 클라이언트나 중간 프록시 서버가 얼마나 오래 캐시할 수 있는지에 대한 지시를 제공한다. Access-Control-Allow-Origin 헤더는 교차 출처 리소스 공유 정책을 정의하여 다른 도메인에서의 리소스 접근을 허용할지 여부를 결정한다.

이 외에도 Server 헤더는 요청을 처리한 서버 소프트웨어 정보를, Set-Cookie 헤더는 클라이언트에 쿠키를 설정하기 위해 사용된다. 보안을 강화하는 Strict-Transport-Security 헤더나 성능 최적화를 위한 Content-Encoding 헤더와 같은 다양한 헤더들이 특정 목적에 따라 응답에 포함될 수 있다. API 설계 시 이러한 응답 헤더를 적절히 구성하는 것은 호환성과 보안, 성능을 보장하는 중요한 요소가 된다.

응답 본문은 API 호출에 대한 서버의 실제 데이터 결과를 담고 있다. 일반적으로 JSON이나 XML과 같은 구조화된 데이터 형식으로 전달되며, 요청한 리소스의 정보나 작업 수행 결과를 포함한다. 응답 본문의 구조는 API 명세서나 API 문서에 사전에 정의되어 있어, 클라이언트는 이를 기반으로 데이터를 올바르게 파싱하고 활용할 수 있다.

응답 본문의 내용은 호출한 엔드포인트와 HTTP 메서드에 따라 크게 달라진다. 예를 들어, 데이터 조회(GET) 요청에 대한 응답에는 요청된 리소스의 세부 정보가 객체나 배열 형태로 포함된다. 반면, 생성(POST)이나 수정(PUT) 요청에 대한 성공 응답에는 새로 생성되거나 갱신된 리소스의 전체 데이터가 담기거나, 작업 성공을 확인할 수 있는 간단한 메시지가 포함될 수 있다.

일관된 응답 본문 구조를 설계하는 것은 API 디자인의 중요한 부분이다. 많은 현대 웹 API는 성공 응답과 에러 처리 응답을 구분하기 위해 공통된 래퍼 형식을 사용한다. 이를 통해 클라이언트 애플리케이션은 상태 코드 확인 외에도 응답 본문 내의 특정 필드를 검사하여 요청의 최종 결과와 추가 데이터를 보다 명확하게 이해할 수 있게 된다.