[네트워크] REST API + RESTful

jh Seo·2025년 5월 29일

컴퓨터 네트워크

네트워크 공부

목록 보기

11/16

REST, RESTful API

REST API(RESTful API 또는 RESTful 웹 API라고도 함)는 REST(Representational State Transfer) 아키텍쳐 스타일의 설계 원칙을 준수하는 API다.
REST API는 애플리케이션을 통합하고 마이크로서비스 아키텍쳐의 구성 요소를 연결하는 유연하고 가벼운 방법 제공

Rest 요약

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고
HTTP Method(POST, GET, PUT, DELETE, PATCH 등)을 통해
해당 자원 (URI)에 대한 CRUD Operation을 적용하는 것을 의미

REST 구성 요소

자원(Resource): HTTP URI
자원에 대한 행위(Verb): HTTP Method
자원에 대한 행위의 내용(Representations): HTTP Message Pay Load

REST API 설계 예시

URI는 동사보다는 명사를, 대문자보다 소문자

		Bad Example > http://flix.com/Running
		Good Example > http://flix.com/run

마지막에 슬래쉬를 포함하지 않음!

		Bad Example >  http://flix.com/run/
		Good Example > http://flix.com/run

언더바 대신 하이픈

		Bad Example > http://flix.com/test_one
		Good Example > http://flix.com/test-one

파일 확장자는 URI에 포함하지 않는다.

		Bad Example > http://flix.com/photo.jpg
		Good Example > http://flix.com/photo

행위를 포함하지 않는다.

		Bad Example >  http://flix.com/delete-post/1
		Good Example > http://flix.com/post/1

REST API 설계 예시 항목별 의도 설명

동사보다는 명사를, 대문자보다는 소문자를 사용한다.

명사 사용
REST API는 리소스(자원)을 중심으로 설계하는 것이 원칙이다.
리소스는 보통 'users', 'posts'처럼 명사로 표현한다.
실제 동작(생성, 조회, 수정, 삭제 등)은 HTTP Method으로 구분하므로,
URI에는 동사가 아닌 명사를 사용해 명확히 나타낸다.
소문자 사용
URI에 대문자를 사용하면 일부 시스템(UNIX계열)에서 대소문자를 구분해 혼란이 생길 수 있다.
또, 일관성 유지와 오류 방지를 위해 소문자가 권장된다.

언더바_ 보다는 하이픈-을 사용한다.

URI경로가 길어질 때 단어 구분을 위해 하이픈을 사용한다.
하이픈은 가독성이 더 좋고, 일부 글꼴에서는 언더바가 잘 안 보이거나 가려진다.
하이픈은 웹 표준에서도 단어 구분자로 널리 쓰인다.

마지막에 슬래쉬/는 사용하지 않는다.

URI 마지막에 슬래쉬를 붙이면, 슬래쉬가 있는 URI와 없는 URI를 서로 다른 리소스로 인식할 수 있어 혼란을 야기한다.
REST API에서는 리소스 식별을 명확히 하기위해 마지막에 슬래쉬를 붙이지 않는다.

행위는 포함하지 않는다.

REST에서는 자원에 대한 행위(조회, 생성, 수정, 삭제 등)을 URI에 명시하지 않고,
HTTP Method로 구분한다.
예를 들어) /users/create 대신 /users에 POST요청을 보내는 식이다.
이렇게 하면 URI가 자원만을 명확하게 나타내고, 행위의 의미는 HTTP 메서드에 위임되어
일관성과 명확성을 높인다.

파일 확장자는 포함하지 않는다.

REST API는 리소스 표현형식을 URI가 아니라, HTTP Header에 지정한다.
파일확장자를 URI에 포함시키면 표현 형식에 종속적이 되어 REST 원칙에 어긋난다.
대신, 클라이언트는 요청시 Accept 헤더로 원하는 미디어 타입을 명시하고,
서버는 Content-Type 헤더로 응답 형식을 알려준다.

REST 설계 원칙

가장 기본적인 수준에서 API는 어플리케이션이나 서비스가 다른 어플리케이션이나 서비스 내의
리소스에 Access할 수 있도록 하는 메커니즘이다.
리소스에 Access하는 어플리케이션이나 서비스가 클라이언트이고, 리소스를 포함하는 어플리케이션이나 서비스는 서버이다.
SOAP 또는 XML-RPC와 같은 일부 API는 개발자에게 엄격한 프레임워크를 적용하지만,
개발자는 거의 모든 프로그래밍 언어를 사용해 REST API를 개발할 수 있으며,
다양한 데이터 형식을 지원한다.
유일한 요구 사항은 아키텍쳐 제약 조건이라고도 하는 다음 6가지 REST 설계 원칙을 준수하는 것.

1. 균일한 인터페이스

동일한 리소스에 대한 모든 API 요청은 요청의 출처에 상관없이 동일하게 표시되어야 함.
REST API는 사용자의 이름 또는 이메일 주소와 같은 동일한 데이터가 하나의 통합 리소스 식별자(URI)에만 속하도록 해야함.
리소스가 너무 커서는 안되며 클라이언트가 필요로 할 수 있는 모든 정보를 포함해야함.

의도 : API가 직관적이고 일관되게 동작하여, 클라이언트와 서버가 독립적으로 개발될 수 있고, 다양한 클라이언트가 동일한 방식으로 서버와 통신할 수 있다.

2. 클라이언트 - 서버 분리

REST API 설계에서 클라이언트 및 서버 어플리케이션은 서로 독립적이여야함.
클라이언트 어플리케이션이 알아야하는 유일한 정보는 요청된 리소스의 URI
서버 어플리케이션과 다른 방법으로 통신할 수는 없다.
서버 어플리케이션은 HTTP를 통해 요청된 데이터에 클라이언트 어플리케이션을 전달하는 것 외에는 클라이언트 어플리케이션을 수정해서는 안 된다.

의도 : 각자의 관심사에 집중함으로써 개발과 유지보수가 용이해지고, 클라이언트와 서버가 독립적으로 발전할 수 있다. 시스템의 확장성과 유연성이 높아진다.

3. 무상태

REST API는 Stateless, 즉 무상태성이므로 각 요청에는 처리에 필요한 모든 정보가 포함되어야 한다.
REST API에는 서버측 세션이 필요하지 않다는 의미
서버 어플리케이션은 클라이언트 요청과 관련된 데이터를 저장할 수 없다.

의도 : 서버 구현이 단순해지고, 서비스 자유도가 높아진다. 서버 확장 및 장애 복구가 쉬워진다.

4. 캐시 가능성

가능한 경우 클라이언트나 서버 측에서 리소스를 캐시할 수 있어야한다.
서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보도 포함되어야한다.
목표는 클라이언트 측의 성능을 향상시키는 동시에 서버 측에 확장성을 높이는 것이다.

의도:불필요한 네트워크 트래픽과 서버 부하를 줄이고, 응답 속도 개선해 전체 시스템 성능 개선하기 위함.

5. 계층화된 시스템 아키텍쳐

REST API에서는 호출과 응답이 서로 다른 계층을 거친다.
일반적으로 클라이언트와 서버 어플리케이션이 직접 연결된다고 가정하지 않는다.
통신 루프에는 다양한 중개자가 있을 수 있다.
REST API는 클라이언트나 서버가 최종 어플리케이션과 통신하는지 중개자와 통신하는지 알 수 없도록 설계해야한다.

의도 : 보안성,확장성,유연성을 높이고, 시스템 구조에 다양한 기능 (ex)로드밸런서, 보안 필터 등)을 추가할 수 있다.

6. 코드 온디맨드(선택 사항)

REST API는 일반적으로 정적 리소스를 전송하지만 경우에 따라 응답에 실행 코드(ex) 자바 에플릿)가 포함될 수 있다.
이러한 경우 코드는 온디맨드 방식으로만 실행되어야 한다.

의도 : 클라이언트의 기능을 동적으로 확장하거나, 사용자 경험 개선. 단 선택적인 사항이다.

REST API 작동 방식

REST API는 HTTP 요청을 통해 통신하여, 리소스 내에서 레코드 생성, 읽기, 업데이트 및 삭제(CRUD)와 같은 표준 데이터베이스 기능을 수행한다.
예시
- Get 요청으로 레코드 검색
- POST 요청으로 새 레코드 생성
- PUT 요청으로 레코드 업데이트
- DELETE 요청으로 레코드 삭제
  -> API 호출에는 모든 HTTP 방식을 사용할 수 있음.
  잘 설계된 REST API는 HTTP 기능이 내장된 웹 브라우저에서 실행되는 웹 사이트와 유사
특정 순간 또는 타임스탬프의 리소스 상태를 리소스 표현이라고 한다.
- 이 정보는 JSON (JAVASCRIPT OBJECT NOTATION), HTML, XLT, Python, PHP 또는 일반 텍스트를 포함해 거의 모든 형식으로 클라이언트에게 전달할 수 있다.
- JSON은 사람과 기계 모두 읽을 수 있고, 프로그래밍 언어에 구애받지 않기 때문에 널리 사용됨.
요청 헤더 및 매개 변수는 메타데이터, 권한 부여, URI(Uniform Resource Identifier), 캐싱, 쿠키와 같은 중요한 식별자 정보를 포함하기 때문에 REST API호출에서 중요
- 요청 헤더 및 응답 헤더는 기존 HTTP 상태 코드와 함께 잘 설계된 REST API 내에서도 사용됨