REST API와 RESTFul

YongJin·2024년 8월 12일

AI스쿨 백엔드 과정 Spring

일단 API 가 뭔지 부터 알아보자

API란?

API(Application Programming Interface)는 애플리케이션 간 상호작용을 가능하게 해주는 인터페이스이다. API는 소프트웨어 구성 요소가 서로 통신할 수 있게 하는 규약이다.
(클라이언트가 서버를 직접적으로 컨트롤 할 수는 없는 노릇이다. api로 서버에게 데이터를 요청하거나, 전송하려면 이런 인터페이스가 필요하다

Rest API / RestFul ?

Rest : 분산 하이퍼미디어 시스템 (>>웹)을 위한 아키텍쳐 스타일
(아키텍쳐 스타일 : 제약조건의 집합)

Rest API : Rest 아키텍쳐 스타일을 따르는 api
그러니깐 엄밀하게는 이 아키텍쳐 스타일을 모두 따라야 Rest를 따른다고 말할 수 있다

밑에서 설명하는 Rest의 특징(제약조건)을 준수하면 RestFul 하다 하고 이런 RestFul한 API를 Rest API라고 한다.

탄생배경

(Rest 이전에 SOAP가 있었는데)
SOAP가 엄청나게 불편하더라...
로이 필딩 : (박사 논문) 내가 Rest라는 개념 만들었어요! http를 더 잘 활용해 봅시다! (https://www.youtube.com/watch?v=RP_f5dMoHFc&t=318s)

REST는 Representational State Transfer라는 용어의 약자로서 2000년도에 로이 필딩 (Roy Fielding)의 박사학위 논문에서 최초로 소개되었다. 로이 필딩은 HTTP의 주요 저자 중 한 사람으로 그 당시 웹(HTTP) 설계의 우수성에 비해 제대로 사용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다고 한다.

HTTP좋은데 어떻게 발전시키면 웹을 망치지않고
(웹가 서버가 서로 의존적이여서 서버를 고치면 클라이언트도 같이 고쳐야 하는 상횡을 피하고) HTTP를 발전시킬 수 있을까?

http와 무슨 관계인가?

설계시 rest의 원칙 (Uniform Interface에 포함)

HTTP 통신에서 어떤 자원에 대한 CRUD 요청을 Resource와 Method로 표현하여 특정한 형태로 전달하는 방식

리소스(HTTP URI로 정의됨)를 어떻게 하겠다(HTTP Method + Payload)라는 형식으로 구조적으로 표현하는 방법.

Rest의 특징(제약조건)

1) Uniform Interface (유니폼 인터페이스)
Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말합니다. >> 특히 이걸 잘 만족시키지 못함

Uniform Interface는 또 4가지 제약조건으로 구성된다

identification of resources (리소스가 URI로 식별되어야 한다)

manipulation of resources through representations (리소스를 조작할 때 HTTP 메세지에 그 표현을 담아서 전송해라)

Self-descriptive messages (메세지는 스스로를 설명해야 한다)

hypermedia as the engine of aplliction state (HATEOAS)
(API가 추가 되어도 웹은 가만히 있고 서버에서만 추가해주면 된다)
밑의 2가지가 오늘날의 REST -API 가 완벽하게 REST가 아닌 이유이다

이게 왜 필요한가? >> 서버와 클라이언트의 독립적인 진화를 위해서이다 (서버 업데이트 했다고 우리가 웹을 이용하는데 전혀 불편함이 없는 것은 이 덕분이다)

2) Stateless (무상태성)
REST는 무상태성 성격을 갖는다.
다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다.
세션 정보나 쿠키정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 비교적 구현이 단순해진다.

3) Cacheable (캐시 가능) > (아직 잘 모르겠음)
REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능합니다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능합니다. HTTP 프로토콜 표준에서 사용하는 Last-Modified태그나 E-Tag를 이용하면 캐싱 구현이 가능하다.

4) code -on -demand (optional)
서버에서 클라이언트에 코드를 보내서 실행시킬 수 있어야 한다 > (JavaScript)

5) Client - Server 구조
REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.

6) 계층형 구조 > (아직 잘 모르겠음)
REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.

RestFul API를 만드는 가이드

자원에 동사형 넣지 마라 > 어떤 행위에 대한 동사는 http 메서드만 사용한다
URI는 동사보다는 명사, 대문자보다는 소문자를 사용하여야 한다
QueryString의 사용을 자제해라(길이에 제한이 있고 배열은 표현하지 못한다)

URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP METHOD를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.

1. URI는 정보의 자원을 표현해야 한다. (리소스명은 동사보다는 명사를 사용)

  GET /members/delete/1 (x)
  
  DELETE /members/1 (o)

1-1 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용한다.

    http://restapi.example.com/houses/apartments
    http://restapi.example.com/animals/mammals/whales

1-2 URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

    http://restapi.example.com/houses/apartments/ (X)
    http://restapi.example.com/houses/apartments  (0)

1-3 URI 경로에는 소문자가 적합하다.
1-4 _하이픈(-)은 URI 가독성을 높이는데 사용 (밑줄 은 사용을 지양한다)
1-5 _파일 확장자는 URI에 포함시키지 않는다. > 어쩔 수 없이 포함하는 경우도 많다

  http://restapi.example.com/members/soccer/345/photo.jpg (X)

2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현해야 한다.

(예시)

	회원 조회
    GET /members/show/1     (x)
    GET /members/1          (o)
    
    회원 정보 추가
    GET /members/insert/2 (x)  - GET 메서드는 리소스 생성에 맞지 않는다.
    POST /members/2       (o)

Http 응답 상태 코드

자원에 대한 접근과 Rest 특징을 잘 지키는 것도 중요하지만 응답을 잘 주는 것도 중요하다
( 전체 응답 코드에 대한 설명 : https://ko.wikipedia.org/wiki/HTTP_%EC%83%81%ED%83%9C_%EC%BD%94%EB%93%9C)

2XX: Success(성공)
클라이언트의 요청이 서버에서 성공적으로 처리되었다는 의미이다.
200 : 클라이언트의 요청을 정상적으로 수행함
201 : 클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)

3XX: Redirection(리다이렉션)
완전한 처리를 위해서 추가 동작이 필요한 경우이다. 주로 서버의 주소 또는 요청한 URI의 웹 문서가 이동되었으니 그 주소로 다시 시도하라는 의미 (웹 페이지 자체를 다른 곳으로 보내야 하는 경우 사용 > 두 회사의 합병으로 예전 회사 홈페이지로의 접속 요청을 합병한 회사의 홈페이지를 보내는 경우)

4XX: Client Error(클라이언트 에러)
없는 페이지를 요청하는 등 클라이언트의 요청 메시지 내용이 잘못된 경우를 의미한다.

5XX: Server Error(서버 에러)
서버 사정으로 메시지 처리에 문제가 발생한 경우이다. 서버의 부하, DB 처리 과정 오류, 서버에서 익셉션이 발생하는 경우를 의미한다.

반드시 지켜야만 하는 철칙이고 지켜지고 있는가?

(지킬 수 없는게 대부분이지만 그냥 Rest api라고 퉁쳐서 부른다.. 로이 필딩 씨는 싫어하겠지만 말이다.)

일단 평소에 쿠팡같은 전자상거래 사이트에서 우리는 로그인을 하지 않고도 사이트의 서비스를 일부 사용가능하지만 핵심 기능은 상태를 유지해야 하는 로그인 기능을 사용해야 한다 (stateless가 지켜지지 않는다) > Rest를 반드시 지키지 않았다고 해서 틀린 개발이라 할 수 있는가?

로그인 쪽 인증과 인가 부분의 조사가 완벽하게 끝나는지는 않았지만 이것은 틀린 주장이다 로그인을 했다 하더라도 요청 시 마다 인증에 대한 정보를 보내고 체크를 다시 해야 하기 때문에 이 부분은 stateless가 맞다
(Rest api의 치명적인 부분 > 지킬 수 없는 이유)
http의 Get 메서드가 Body를 지원하지 않는다
현재는 GET 이 Body를 전달 할 수 있게 바뀌긴 했지만, 아직도 대부분의 경우 사용할 수 없다. post의 Body에 데이터를 넣고 동사를 사용한다

https://www.youtube.com/watch?v=RP_f5dMoHFc&t=318s(그런 Rest api로 괜찮겠는가? 32분쯤 참고) > 이미 많은 개발자들이 rest api를 엄밀하게 지키지 않고 있지만 rest api라고 한다