REST API 잘 사용하기

1. REST API란??

Representational state transfer의 약자로 2000년에 Roy Fielding(로이 필딩)의 논문에 처음 등장한 용어입니다. REST는 분산 하이퍼미디어 시스템의 구조화 스타일에 대해 다룹니다. ‘분산 하이퍼미디어 시스템’은 웹을 지칭합니다. 클라이언트와 서버 간의 효율적인 통신을 지원합니다.

2. REST 구성

• 자원(RESOURCE) - HTTP URI
• 행위(Verb) - HTTP METHOD
• 표현(Representations): 자원에 대한 행위의 내용 - HTTP Message Pay Load

3. REST의 특징

1. Uniform Interface(일관된 인터페이스)
   • 리소스가 URI로 식별돼야 합니다.
   • HTTP method로 리소스를 조작해야 한다.
   • Self-Descriptive Messages(자체 표현 구조)
     • 메시지만 보고 그 의미를 이해할 수 있어야 한다.
       

       {"id": 1, "name": "테스트"}

     아래의 메시지를 보고 무슨 의미인지 알 수 있을까요? 물론 유추는 할 수 있을 겁니다. 문제는 메시지만 보고서
     1. 요청이 정상적으로 처리되었는지 알 수 없습니다.
     2. 형식을 제대로 알 수 없습니다. JSON을 알고 있다면 JSON이라고 말하겠지만 XML, HTML 어떠한 형식도 공부하지 않은 사람은 위 형식이 무엇인지 알 수 없을 것입니다.
     3. id가 어떤 의미인지? name이 사람의 이름인지 동물의 이름인지 어떤 제품의 이름인지 알기 어렵습니다.
     위의 문제점을 고쳐 Self-Descriptive Messages로 표현해 봅시다.
     

     1 HTTP/1.1 200 OK
     2 Content-Type: application/json
     3 {"id":1, "name":"테스트"}

     이렇게 하면 1번 과 2번 의 문제는 해결할 수 있습니다. 하지만 3번은 아직도 해결하지 못했습니다.
     3번은 두 가지 방법을 통해 해결할 수 있습니다.
     
     • media-type을 정의
     • Link header에 명세를 추가
   • 애플리케이션의 상태를 Hypermedia를 통해 전이해야 한다.
2. Stateless(무상태)
   • 서버가 이전의 모든 요청과 독립적으로 모든 클라이언트 요청을 완료하는 통신 방법입니다. 모든 요청은 무상태이 거나 다른 요청과 분리됩니다.
   • 세션 정보, 쿠키정보를 별도로 저장하지 않고, API 서버는 들어오는 요청만 처리하면 됩니다.
   • 이렇게 하면 서비스의 자유도를 높일 수 있고, 서버에서 불필요한 정보를 관리하지 않아도 되기 때문에 구현이 단순해집니다.
3. Client-Server 구조

• 제일 중요한 원칙은 관심사의 분리(Seperation of concern)입니다.
• 데이터의 저장에 대한 관심사와 사용자 인터페이스에 대한 관심사를 분리, 클라이언트 측면에서는 여러 플랫폼에 대한 사용자 인터페이스의 이식성(portability)을 개선할 수 있고, 서버 측면에서는 서버 측의 구성요소를 단순화함으로써 확장성(scalability)을 개선할 수 있습니다.

4. Cacheability (캐시 가능성)
   • 응답 메시지의 데이터에 캐시 가능한지, 가능하지 않은지 등에 대해 언급해야 한다. 응답 메시지가 캐시 가능하다면 클라이언트 캐시는 그 메시지를 재사용할 권리가 생긴다.
   • 예를 들어, 모든 페이지마다 공통의 이미지와 페이지 넘버가 있다고 할 때 새로운 페이지를 방문할 때마다 서버는 동일한 이미지, 페이지 넘버를 전송해야 합니다. 이는 매우 번거롭고, 불필요한 비용이 드는 일입니다. 그래서 클라이언트는 첫 번째 응답에서 공통 이미지, 페이지 넘버를 캐싱하거나 저장한 다음 캐시에서 직접 이미지를 사용합니다.
   • HTTP 응답 메시지 헤더에서 데이터의 캐시 사용성에 대해 서술하는 Cache-control 헤더가 있는 것이 대표적이다.
5. Layerd System (계층화 시스템)
   • 시스템을 여러 계층으로 나누어 각 계층이 독립적으로 작동하되, 서로 협력하여 전체 시스템의 기능을 이루는 것입니다. 장점은 시스템의 유연성과 확장성을 향상할 수 있다는 것입니다.
   • 예를 들어, 애플리케이션 로직을 처리하는 계층에서 부하가 많이 발생한다면, 해당 계층만을 대상으로 서버를 추가적으로 배포함으로써 시스템의 전체 성능을 향상 시킬 수 있습니다.
   • 각 계층은 독립적으로 운영되기 때문에, 한 계층에서의 변경이나 실패가 다른 계층에 영향을 주지 않아 시스템의 안정성을 높일 수 있습니다.
6. On-Demand Codes(온디맨드 코드)
   • 클라이언트가 필요할 때 서버로부터 코드를 다운로드하고 실행하는 기능을 말합니다. 이 기능은 클라이언트에 유연성과 확장성을 제공할 수 있다는 장점이 있다.

4. REST API 중심 규칙

REST에서 가장 중요한 기본 규칙은 두 가지입니다.

1. URI는 정보의 자원을 표현해야 한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)으로 표현한다.

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

• member의 id가 1인 정보의 resource를 표현한다면?

# bad
GET /members/show/1

#good
GET /members/1

URI는 자원을 표현하는데 중점을 둬야 합니다. show라는 행위(동사)는 이미 GET이라는 HTTP Method로 충분히 표현이 가능합니다.

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

#bad
GET /members/delete/1

#good
DELETE /members/1

위 코드에서 #bad 코드를 보면 URI에 delete라는 동사가 들어가서 1번 원칙을 위배합니다.

delete라는 행위를 하고 싶다면 2번 원칙처럼 HTTP Method를 사용해서 표현해야 합니다.

참고

HTTP Method

Method	Action	역할	페이로드
GET	index/retrieve	모든/특정 리소스를 조회	x
POST	create	리소스 생성	o
PUT	replace	리소스의 전체를 교체	o
PATCH	modify	리소스의 일부를 수정	o
DELETE	delete	모든/ 특정 리소스 삭제	x

응답 코드

https://www.restapitutorial.com/httpstatuscodes.html#

서버의 응답에는 작업 성공에 대한 정보를 클라이언트에 알리는 상태 코드가 포함되어 있습니다. 개발자로서 모든 상태 코드를 알 필요는 없지만(상태 코드가 많음) 가장 일반적인 상태 코드와 사용 방법은 알아야 합니다.

상태코드	의미
200 (OK)	성공적인 HTTP 요청에 대한 응답 코드입니다.
201 (CREATED)	성공적으로 생성된 HTTP 요청에 대한 응답 코드입니다.
204 (NO CONTENT)	성공적인 HTTP 요청에 대한 응답이지만, 응답 본문에 아무것도 반환되지 않습니다.
400 (BAD REQUEST)	잘못된 요청 구문, 잘못된 클라이언트 요청에 대한 응답 코드입니다.
403 (FORBIDDEN)	클라이언트가 엑세스 권한이 없는 리소스에 요청을 했을 때 응답 코드입니다.
404 (NOT FOUND)	삭제되었거나 아직 존재하지 않을 수 있는 리소스에 요청하였을 때 응답 코드입니다.
500 (INTERNAL SERVVER ERROR)	서버에 문제가 있을 경우 사용하는 응답 코드입니다.

참고

https://aws.amazon.com/ko/what-is/restful-api

https://meetup.nhncloud.com/posts/92[https://velog.io/@kms8571/REST를-위한-uniform-interface](https://velog.io/@kms8571/REST%EB%A5%BC-%EC%9C%84%ED%95%9C-uniform-interface)https://poiemaweb.com/js-rest-api#:~:text=%233.-,REST
https://shoark7.github.io/programming/knowledge/what-is-rest