TIL-25.11.25

이준연·2025년 11월 25일

Today I learned

학습 키워드

HTTP
API
REST API

HTTP(Hyper Text Transfer Protocol) 개념

웹(Web)에서 데이터를 주고 받기 위한 통신 규칙(프로토콜)
클라이언트(웹 브라우저, 애플리케이션)와 서버 간의 요청(Request)과 응답(Response)을 통해 작동한다.

HTTP 주요 특징

무상태성(Stateless)
- 서버가 클라이언트의 이전 상태를 기억하지 않습니다.
비연결성(Connectionless)
- 클라이언트가 요청을 보내고 서버가 응답을 마치면, TCP/IP 연결을 끊습니다.
- 최소한의 자원으로 서버를 유지.

HTTP 요청(Request)

시작줄
- Version
  - 클라이언트가 요청을 보내 때 어느 버전에 HTTP 요청을 보냈는지 알려줍니다.
  - 각 HTTP 버전에 특징이 다르기 때문입니다.
- Method
  - 객체 지향 프로그래밍에서 객체가 수행할 수 있는 동작 또는 기능을 의미합니다.
- URL
  - 홈페이지 주소(IP주소)
  - :80(포트)
  - /items(경로)
헤더
- Content-Type
  - 본문(Body)에 담긴 데이터가 어떤 형식인지 알 수 있게하는 정보입니다.
- Accept
  - 클라이언트 전달 받을 수 있는 데이터를 서버에게 알려주기 위한 정보입니다.
본문
- JSON
  - 객체 형태의 key: value 쌍으로 이루어진 텍스트 형식입니다.
- HTML
  - HTML 파일을 텍스트 형로 전달합니다.

HTTP 요청 메서드

POST - 서버에 데이터를 전송(추가)할 때 사용 (등록)
GET - 정보를 요청하기 위해 사용 (조회)
HEAD - Get 요청과 동일하지만, 응답 바디를 제외한 헤더 정보만을 요청
PUT - 정보를 업데이트(갱신)하기 위해 사용, 정보 변경 (수정)
PATCH - 리소스 일부분을 수정
DELETE - 정보를 삭제하기 위해 사용 (삭제)
OPTIONS - 서버에서 지원하는 HTTP 메서드의 목록을 요청할 때 사용
CONNECT - 프록시 동작의 터널 접속을 변경

그 외의 정보

멱등성(Idempotent)
- 여러번 수행해도 결과가 같음을 의미한다. 즉, 호출로 인하여 데이터가 변형이 되지 않는다는 것을 의미한다.

데이터베이스의 기본 4대 요소(CRUD)

Create, Read, Update, Delete의 앞글자를 따와서 만들어졌으며, 단어 뜻 그대로 생성, 조회, 수정 삭제 4가지의 기능을 의미한다. 데이터베이스의 요소에서 확장되어, 대부분의 컴퓨터 소프트웨어가 가지는 기본 기능을 일컫는데에도 사용된다.

POST

새로운 리소스를 생성할 때 사용되는 HTTP 메서드다. 구체적으로, Post는 부모 리소스의 하위 리소스를 생성하는데 사용됩니다. 성공적으로 리소스를 생성하면 201(Created) HTTP 응답을 반환한다.

멱등성 ❌ : 동일한 POST 요청을 여러 번 보내더라도 항상 같은 결과물을 보장하지 않는다.
동일한 POST 요청을 두 번 보낸다면 같은 정보를 담은 두 개의 다른 리소스가 생성될 가능성이 높다.

// 시작 줄
Version: HTTP /1.1
Method: POST 
URL: 홈페이지 주소:80/items

// 헤더
content-Type: "application/json" // 본문의 데이터 형식을 명시. JSON

// 바디
{
  data: "example"
}

요청 본문 ⭕ : 요청 시 본문(Body)에 데이터를 포함하여 전송한다.
콘텐츠 유형 : Content-Type 헤더를 사용하여 본문의 데이터 형식을 명시해야 한다.
리소스가 성공적으로 생성되면 201(Created) 응답 코드와 함께 생성된 리소스에 대한 정보를 반환한다.

GET

데이터를 조회하거나(Read) 검색(Retrieve)할 때에 사용되는 메서드다. GET 요청이 성공적으로 이루어지면 서버는 XML, JSON, HTML 등의 형태로 데이터를 반환한다. 이때 200(OK) 응답 코드를 리턴. 실패 시 404(Not Found) 또는 400(Bad Request) 에러가 발생한다.

데이터 읽기 전용 : HTTP 명세에 따르면 GET 요청은 오직 데이터를 읽을 때만 사용되어야 하며, 서버의 데이터를 수정하는데 사용되어서는 안 된다.
멱등성 : GET 요청은 멱등성을 가진다. 이는 도일한 GET 요청을 여러 번 수행하더라도 서버의 상태가 변하지 않으며, 항상 동일한 응답을 받는다는 것을 의미한다.

GET /items/1

요청 본문 ❌ : 본문(Body)를 가지고 있지 않아 본문의 데이터 형식을 필요로 하지 않는다.
조회할 데이터에 대한 정보는 URL의 쿼리 파라미터로 전달된다.
데이터 조회에 성공하면 응답 본문에 데이터를 포함하여 성공 응답을 보낸다. (이 때 데이터 값 저장)
캐싱 가능 : GET 요청은 캐싱이 가능하다. 동일한 데이터를 다시 조회할 경우, 캐시된 데이터를 사용하여 조회 속도를 높일 수 있다.

그외의 정보

쿼리 파라미터(Query Parameter)
- URL 뒤에 물음표(?)와 함께 붙는 키-값(Key-Value) 쌍입니다.
- 여러 개의 쿼리 파라미터를 전달하려면 파라미터 사이에 앰퍼샌드(&)를 추가해서 하나의 문자열(string)로 전달해야 합니다.

PUT

리소스를 생성하거나 업데이트하기 위해 서버로 데이터를 보내는데 사용한다.

멱등성 : PUT 요청은, 멱등성을 가져, 동일한 PUT 요청을 여러 번 보내더라도 항상 동일한 결과가 생성된다.

// 시작 줄
Version: HTTP /1.1
Method: PUT 
URL: 홈페이지 주소:80/items/1


// 헤더
Content-Type : "application/json"

// 바디
{
  date : "update example"
}

요청 본문 ⭕ : 요청 시 본문(Body)에 데이터를 포함하여 전송한다.
콘텐츠 유형 : Content-Type 헤더를 사용하여 본문의 데이터 형식을 명시해야 한다.
URL을 통해 어떤 리소스를 수정할지 지정한다. 수정할 데이터 값은 Body에 포함된다.
데이터 조회에 성공하면 Body에 지정한 데이터를 포함하여 성공 응답을 보낸다.

DELETE

지정된 리소스를 삭제하는데 사용한다.

DELETE /items/1

요청 본문 ❌ : 본문(Body)를 가지고 있지 않아 본문의 데이터 형식을 필요로 하지 않는다.
URL을 통해 어떤 리소스를 삭제할지 지정한다.
데이터 삭제에 성공하면 Body 없이 성공응답(보통 200 OK), 실패 시 204(No Content)를 보낸다.

HTTP 응답 코드

1xx : 정보 제공(Informational)
2xx : 성공(Success)
3xx : 리다이렉션(Redirection)
4xx : 클라이언트 에러(Client Error)
5xx : 서버 에러(Server Error)

API

애플리케이션 프로그래밍 인터페이스(Application Programming Interface)의 약자입니다.
서로 다른 소프트웨어 애플리케이션이 통신하고 데이터를 주고받을 수 있도록 하는 규칙과 약속의 집합입니다.
API는 소프트웨어 간 상호작용의 중간 다리 역할을 하며, 기존 기능을 활용하여 개발 시간과 비용을 절약하는 데 도움을 줍니다.

REST API

표현 상태 전송(Representational State Transfer) 아키텍처 스타일을 따르는 API로 네트워크를 통해 클라이언트와 서버가 자원의 상태를 주고받는 방식을 정의합니다.

표현(Representational)
- 서버의 자원(Resouce)을 클라이언트가 이해할 수 있는 형태로 쉽게 표현하는 방식을 말합니다.
  ex) JSON, HTML

여기서 자원이란 서버가 관리하는 모든 데이터들을 의미하며, 해당 자원을 URL 경로로 식별합니다.

상태(State)
- 서버가 관리하는 자원에 현재 상태를 의미합니다
  - 등록
  - 수정
  - 삭제
Transfer(전송)
- 클라이언트가 서버에게 자원의 상태를 요청하고, 서버는 해당 상태를 클라이언트에게 전달합니다.
- 주로 HTTP 통신을 사용합니다.

즉, REST API는 웹 자원을 URL로 식별하고, 그 자원의 표현을 HTTP 표준에 맞게 주고받는 원칙을 의미합니다.

REST 6가지 원칙

균일한 인터페이스(Uniform Interface) - 표준의 핵심
- 모든 자원은 고유한 주소로 식별되어야 합니다.
- 헤더 등을 통해 자신의 상태를 정의할 수 있어야 한다.
클라이언트-서버(Client-Server) - 역할 분리
- 클라이언트는 사용자 경험만을 책임지고, 서버는 데이터와 로직만을 책임진다.
무상태성(Stateless) - 서버는 당신을 기억하지 않는다.
- HTTP의 무상태성 특징을 그대로 따릅니다.
주문형 코드(Code-On-Demand) - 필요할 때 기능을 전송하다.
- 서버 데이터 뿐만 아니라 실행 가능한 코드를 클라이언트에 전송하여, 클라이언트의 기능을 일시적으로 확장시킬 수 있음을 의미합니다.
- 다양한 형식의 데이터를 다룰 수 있다.
캐시 가능(Cacheable)
- 자주 변하지 않는 데이터는 임시 저장된 것을 사용하여 속도를 높이고, 서버 부담을 줄입니다.
계층형 시스템(Layered System)
- 보안, 성능 등을 위해 시스템을 확장해도 클라이언트에 영향을 주지 않는다

REST의 모든 원칙이 지켜지는 경우는 극히 드뭅니다. REST 설계 원칙은 좋은 API를 설계하기 위한 원칙이지 법이 아니기 때문입니다.
균일한 인터페이스(Uniform Interface), 클라이언트-서버(Client-Server), 무상태성(Stateless)이 가장 많이 차용되는 원칙입니다.

API 명세서 작성의 중요성 및 구성 요소

API 명세서는 Server와 Client 간의 일종의 계약서 역할을 하며, 이를 통해 Frontend와 Backend 개발자가 동시에 개발할 수 있게 됩니다.
명세서가 없으면 누가 수정해야 할지, 어떤 순서로 개발해야 할지 애매해져 개발에 문제가 발생합니다.
적절한 API 도출을 위한 5가지
- 누가 사용할지(Who)
- 무엇을 다룰지(What)
- 어떻게 다룰지(How)
- 무엇이 필요한지(Parameter)
- 무엇을 돌려줄지(Return)
요청 명세서(Request Specification)의 필수 구성 요소는 Method, Endpoint, 요청(Parameter), Header 정보, 그리고 Body입니다.
Endpoint 작성 시에는 동사가 아닌 명사를 사용하며, 기본적으로 복수형(/items, /users)을 사용해주는 것이 RESTFUL 원칙입니다.

API 명세서 중요사항

응답 명세서(Response Specification)는 상태 코드(Status Code), Header, 그리고 본문(Body)으로 구성됩니다.
응답 명세서에는 성공(2xx)뿐만 아니라 Client 오류(4xx)와 Server 오류(5xx) 상황에 대한 응답도 명시해야 합니다.
오류 발생 시, 오류의 원인과 코드를 Body에 명시하여 Client가 User에게 적절히 표현할 수 있도록 해야 합니다.
전체 API 명세서에는 Base URL, Method, Endpoint, 기능 설명, 그리고 선택적 Query Parameter 정보가 포함됩니다.
POST 요청(생성) 시에는 Request Body에 필수 항목(예: 이름, 가격)을 명시하고, 성공 시 201(Created)과 ID가 부여된 객체를 반환합니다.
PUT 요청(수정) 시에는 Endpoint에 ID 값을 포함하여 특정 Item을 지정하고, Request Body에 수정할 내용을 전달하며, 성공 시 200(OK)을 반환합니다.
DELETE 요청(삭제) 시에도 Endpoint에 ID 값을 포함하며, 성공 시 204(No Content)를 반환하고, 삭제할 Item이 없으면 404(Not Found)를 반환합니다