Harvey's TechNote

RESET API란?

 REST API는 Representational State Transfer API의 약자로 Roy Fileding이란 사람의 박사학위 논문에서 웹(http)의 장점을 최대한 활용할 수 있는 아키텍처로 처음 소개 되었습니다.

 REST API는 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고 HTTP 프로토콜을 통해서 요청과 응답을 정의하는 방식을 의미합니다. 예를 들어 설명하자면 식당의 메뉴판을 생각해 보세요. 식당의 메뉴판이 알아보기 쉽고 잘 작성되어 있을수록 메뉴판의 역할을 잘 수행할 수 있습니다.  이러한 메뉴판이 REST API가 되는 것이고 이를 더욱 좋게 디자인하는 것이 중요합니다.

원칙

REST API를 설계할 때는 아래와 같은 원칙을 따라야합니다.

• URI는 자원을 나타내야 한다.
• 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현한다.
• 메시지는 자원의 상태를 전달한다.

예시!!

좋은 REST API의 예시를 들어 설명해 보겠습니다!. 아래 예시는 사용자 정보를 가져오고 생성하는 API를 제공하는 간단한 회원 가입 서비스입니다.

1. 사용자 정보 가져오기 API

• 자원: 사용자 정보(User Info)
• URI: /users/{user_id}
• HTTP 메서드: GET

URI에서 {user_id} 부분은 가져올 사용자의 ID를 나타냅니다. 따라서, 클라이언트는 /users/1234와 같은 식으로 URI를 구성하여 특정 사용자 정보를 가져올 수 있습니다.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "user_id": 1234,
  "name": "YUNSU Keum",
  "email": "keumyunsu@example.com"
}

이 API는 다음과 같은 응답을 반환합니다.

2. 사용자 정보 생성 API

• 자원: 사용자 정보(User Info)
• URI: /users
• HTTP 메서드: POST

이 API는 클라이언트에서 새로운 사용자 정보를 제공하면, 서버에서는 새로운 사용자를 생성하고, 생성된 사용자 정보와 함께 성공적인 응답을 반환합니다.

<요청>

POST /users HTTP/1.1
Content-Type: application/json

{
  "name": "YUNSU KEUM",
  "email": "keumyunsu@example.com",
  "password": "secret"
}

<응답>

HTTP/1.1 201 Created
Content-Type: application/json

{
  "user_id": 5678,
  "name": "KEUM YUNSU",
  "email": "keumyunsu@example.com"
}

위 REST AIP가 좋은 이유를 정리해서 설명해 보겠습니다.

• URI는 자원을 명확하게 식별할 수 있도록 구성되어 있습니다. 사용자 정보를 가져오는 API는 /users/{user_id}와 같이 구성되어 있으며, 사용자 정보를 생성하는 API는 /users와 같이 구성되어 있습니다.
• HTTP 메서드는 자원에 대한 CRUD(Create, Read, Update, Delete) 동작을 나타내는 데 사용되었습니다. 사용자 정보를 가져오는 API는 GET 메서드를 사용하며, 사용자 정보를 생성하는 API는 POST 메소드를 사용합니다.
• 응답은 JSON 형식으로 반환되며, HTTP 상태 코드와 함께 전송됩니다. 응답은 클라이언트가 요청한 자원에 대한 적절한 상태와 함께 반환되므로, 클라이언트는 응답을 쉽게 처리할 수 있습니다.

특징

그리고 REST API의 주요한 특징은 다음과 같습니다.

• 높은 호환성: REST API는 HTTP 프로토콜을 기반으로 하기 때문에, HTTP를 지원하는 모든 플랫폼에서 호환됩니다.
• 분리된 클라이언트/서버 구조: REST API는 클라이언트와 서버가 분리된 구조로 설계되어 있습니다.
• 캐시 가능: HTTP 프로토콜 특성상 캐시를 사용할 수 있어, 서버 부하 감소와 네트워크 병목 현상 감소 등의 이점을 가집니다.
• 자체 표현 구조: REST API에서는 XML, JSON 등의 다양한 데이터 포맷을 사용하여 데이터를 전송합니다

장점

마지막으로 REST API를 통해 얻을 수 있는 장점들입니다.

• 유연성: REST API는 다양한 플랫폼과 언어에서 사용할 수 있으며, 기존의 시스템과도 쉽게 연동할 수 있습니다.
• 가독성: REST API에서는 URI를 통해 자원을 표현하므로, 어떤 요청인지 쉽게 파악할 수 있습니다.
• 확장성: REST API는 새로운 자원을 쉽게 추가하고, 기존 자원의 기능을 확장할 수 있습니다.

HTTP(Message)란 Hypertext Transfer Protocol의 약자로, 웹 브라우저와 웹 서버가 통신하기 위한 프로토콜입니다. HTTP는 클라이언트(웹 브라우저)와 서버 간의 요청과 응답 메시지를 주고받습니다. 이번엔 HTTP의 Message에 대해 차례대로 자세히 알아보겠습니다.

HTTP Message란?

HTTP Message는 크게 Start line, 헤더(Header)와 본문(Body)으로 구성됩니다. 헤더는 HTTP 메시지에 대한 정보를 포함하고 있으며, 본문은 메시지에 대한 실제 데이터를 포함합니다.Start line에는 요청이나 응답의 상태를 나타내고 항상 첫 번째 줄에 위치합니다. 응답에서는 status line이라고 부릅니다. 

HTTP Request Message의 형식

HTTP Request Message는 다음과 같은 형식으로 구성됩니다.

Post /api/login HTTP/1.1      	   // HTTP Method 요청 URL HTTP Version
HOST: www.exampleyunsu.com         // Header1: Value1
Content-Type: application/json     // Header2: Value2
...

	   BODY

HTTP Request Message는 HTTP Method, 요청 URL, HTTP Version, 헤더, 본문으로 구성됩니다.

HTTP Response Message의 형식

HTTP Response Message는 다음과 같은 형식으로 구성됩니다.

HTTP/1.1 403 Forbidden               // HTTP Version Status Code Reason Phrase
Server: Apache                       // Header1: Value1
Date: WED, 10 Aug 2023 09:44:32 GMT  // Header2: Value2
...

	   BODY

HTTP Response Message는 HTTP Version, 상태 코드(Status Code), Reason Phrase, 헤더, 본문으로 구성됩니다.

HTTP Message의 헤더(Header)

HTTP Message의 헤더는 클라이언트와 서버 간에 전송되는 메시지에 대한 정보를 담고 있습니다. 일반적으로 다음과 같은 정보를 포함합니다.

• Content-Type: 본문의 데이터 타입을 나타냅니다.
• Content-Length: 본문의 길이를 나타냅니다.
• User-Agent: 클라이언트의 사용자 에이전트 정보를 나타냅니다.
• Accept: 클라이언트가 받아들일 수 있는 미디어 타입을 나타냅니다.
• Host: 요청된 URL의 호스트 정보를 나타냅니다

HTTP Message의 Body

HTTP Message의 body는 Request나 Response에 대한 실제 데이터가 들어갑니다. body는 어떠한 형식으로든 데이터를 전달할 수 있습니다.

HTTP에서는 이에 따라 다양한 데이터 형식을 지원하는데. 예를 들어, HTML, XML, JSON, 이미지 파일, 동영상 파일 등이 있습니다. 따라서, HTTP Message의 본문은 전송하려는 데이터 형식에 따라 적절한 Content-Type 헤더 필드를 포함해야 합니다. 아래 body가 포함되어있는 예시를 확인해 보겠습니다.

Post /api/login HTTP/1.1      
HOST: www.exampleyunsu.com       
Content-Type: application/json 
					//헤더와 본문을 구분하는 빈줄이 있습니다.
{
    "username": "Yunsu",
    "password": "Goodboy1234"
}

위 HTTP Request Message는 POST방식으로 /api/login에 대한 요청이고 body는 JSON 형식으로 이루어져 있습니다. Content-Type으로 확인 가능합니다. 

마찬가지로 HTTP Response Message에서도 body를 포함하는데 아래 HTML 형식으로 응답 body를 포함하는 HTTP Response Message를 확인해 보겠습니다.

HTTP/1.1 200 OK
Content-Type: text/html

<!DOCTYPE html>
<html>
<head>
    <title>Example Page</title>
</head>
<body>
    <h1>Welcome to YUNSU Page!</h1>
</body>
</html>

위의 예시에서 HTTP Response Message는 상태 코드 200 OK로 성공적인 응답을 보내고 있으며, 응답 body는 HTML 형식으로 작성되어 있습니다. 응답 내용의 Content-Type 헤더 필드에서 body부분이 HTML 형식임을 나타냅니다.

HTTP Message의 상태 코드(Status Code)

HTTP Response Message에서는 상태 코드(Status Code)라는 것이 중요한 역할을 합니다. 상태 코드는 서버가 요청을 받아들였는지, 문제가 있었는지 등의 상태를 나타내는 3자리 숫자로 이루어져 있습니다.

예를 들어, 200번대는 성공적인 요청에 대한 상태 코드를 의미하고, 400번대는 클라이언트 측에서 잘못된 요청을 보낸 경우에 대한 상태 코드를 의미하며, 500번대는 서버 측에서 오류가 발생한 경우에 대한 상태 코드를 의미합니다.

아래 자주 사용되는 상태 코드를 정리해 보았습니다. 

• 200 OK: 요청이 성공적으로 처리되었음을 나타냄
• 400 Bad Request: 클라이언트 측에서 잘못된 요청을 보냄
• 401 Unauthorized: 인증되지 않은 사용자가 보호된 리소스에 접근하려고 시도함
• 404 Not Found: 요청한 리소스를 찾을 수 없음
• 500 Internal Server Error: 서버에서 오류가 발생함

결론

HTTP Message는 HTTP 프로토콜에서 데이터를 주고받는 데 사용되는 녀석이다!.

클라이언트와 서버 간 요청을 주고받게 해 주고 HTTP Message는 Start-Line, Header, Body로 이루어져 있다. 

아래는 MDN에서 상태 코드들에 대한 정보를 나열해 둔 곳입니다.

https://developer.mozilla.org/ko/docs/Web/HTTP/Status