ETC./REST

REST API

pathas 2020. 4. 16. 11:10

REST API

REST(REpresentational State Transfer)
로이 필딩(Roy Fielding)의 2000년 논문에서 처음 소개되었으며,
발표 당시의 웹이 HTTP의 설계 상 우수성을 제대로 사용하지 못하고 있는 상황을 보고
웹의 장점을 최대한 활용할 수 있는 아키텍쳐로서 REST를 제시

REST는 HTTP 프로토콜을 의도에 맞게 디자인하도록 유도하며,
REST의 기본 원칙을 성실히 지킨 서비스 디자인을 "RESTful"하다고 표현

1. REST API 속성

  1. 서버에 있는 모든 자원은 각 자원당 클라이언트가 바로 접근할 수 있는 고유 URI가 존재
  2. 모든 요청은 클라이언트가 요청할 때마다 필요한 정보를 주기 때문에 서버에서는 세션 정보를 보관할 필요가 없음
    → 서비스 자유도가 높아지고 유연한 아키텍쳐 적용이 가능
  3. HTTP 메서드 사용
    자원에 대한 행위는 GET, POST, PUT, DELETE 등의 HTTP Method로 표현
  4. 서비스 내에 하나의 자원이 주변에 연관된 자원들과 연결되어 표현되어야 함

2. REST API 구성

REST API는 자원(Resource), 행위(Verb), 표현(Representations)의 3가지 요소로 구성
REST는 자체 표현 구조(Self-descriptiveness)로 구성되어 REST API만으로 요청 이해 가능

구성 요소 내용 표현 방법
Resource 자원, DB에 저장된 데이터, 이미지/동영상/문서(pdf 등)와 같은 파일,서비스를 모두 포함 HTTP URL
Verb 자원에 대한 행위 HTTP Method
Representations 자원에 대한 행위의 내용 HTTP Message Pay Load

3. Resource

REST에서는 자원에 접근할 때 URI(Uniform Resource Identifier) 사용

URI는 자원의 위치를 나타내는 일종의 식별자로,
URI 설계 시 지켜야하는 규칙이 있음

① ' / '

  • 슬래시( / )는 계층 관계를 나타내는 데 사용 ex) http://www.happy-zoo/animals/dogs/john
    위의 사이트에서 'john' 개의 정보를 찾을 때
    'happy-zoo'부터 단계를 거쳐서 'john'까지 도달
  • 슬래시는 계층 구조를 나타내기 때문에 마지막 자원에는 슬래시를 포함하지 않음
    폴더 안에 있는 파일을 찾을 때와 같은 구조라고 생각하면 이해하기 쉬움

② URI를 이루는 자원들은 동사보다 명사를 사용

  • 자원 조회 시, get과 같은 동사를 사용하지 않고 자원의 종류나 이름 표기
    ex) /getTodos/1 → BAD
    /todos/1 → GOOD
  • 자원 간 관계 표현 시, [/users/{userid}/devices] 와 같이 [/리소스명/리소스 ID/관련 리소스명] 으로 표현

③ URI에서는 '_'(언더바)보다 '-'(하이픈) 권장

가독성이 중요한 언더바는 자원 해석에 혼란을 줄 수 있음

④ URI 작성에는 소문자가 적합

RFC 3986(URI 문법 형식)에 따르면 URI 스키마와 호스트를 제외하고는
대소문자를 구별하기 때문에 대문자의 사용은 피하고 소문자만 사용

⑤ 파일 확장자는 URI에 포함시키지 않음

URI에 확장자를 포함시키지 않고 Accept header 사용

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

GET / members/soccer/345/photo HTTP/1.1 Host:
restapi.example.com Accept: image/jpg

4. HTTP Method

주로 아래 표의 다섯 가지 메서드를 사용하여 CRUD 구현

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

※ 데이터를 조회할 때는 GET을 많이 사용하고 데이터를 추가, 삭제, 수정할 때에는 POST를 많이 사용

5. Endpoint

같은 URI에 대한 요청을 해도 HTTP Method를 구분해 주는 것을 Endpoint라고 함

Message

메시지는 HTTP header와 body, 응답 상태 코드로 구성
header와 body에 포함된 메시지는 메시지를 처리하기 위한 정보를 포함

Body

자원에 대한 정보 전달, 데이터 포맷: JSON / XML / 사용자 정의 포맷
→ 요즘에는 JSON을 많이 사용

Header

HTTP 바디에 어떤 포맷의 데이터가 담겼는지 정의
요청 HTTP 헤더는 'Accept'항목으로, 응답 HTTP 헤더는 'Content-type'으로 컨텐츠 타입 설명

응답 상태 코드

  • 메시지는 따로 표기되는 것이 아니라 코드와 함께 표현되는데
    표에서는 편의상 나누어서 작성
    F12(개발자탭) - Network - Status Code 에서 확인 가능
    ex) 200 or 200 OK
  • 이 외에도 훨씬 더 많은 상태 코드들이 있으며 여기서는 자주 사용되는 상태 코드만 다룸

2XX 성공 응답

코드 메시지 설명
200 OK 요청을 성공적으로 수행함
GET: 리소스를 메시지 바디에 담아옴
POST: 수행 결과에 대한 리소스가 메시지 바디에 담겨 전송
201 Created 요청이 성공적이었으며 그 결과로 새로운 리소스 생성
이 응답은 일반적으로 POST 요청 또는 일부 PUT 요청 이후에 따라옴

3XX 리다이렉션 메시지

코드 메시지 설명
301 Moved Permanently 요청한 리소스의 URI가 변경되었음을 의미
새로운 URI가 응답에서 주어질 수도 있음

4XX 클라이언트 에러 응답

코드 메시지 설명
400 Bad Request 잘못된 문법으로 요청을 해서 서버가 요청을 이해하지 못함
401 Unauthorized 클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때의 응답 코드
HTTP 표준에서는 "미승인(unauthorized)"임을 명확히 하고 있으나, 의미상 "비인증(unauthenticated)"을 의미
404 Not Found 서버가 요청받은 리소스를 찾을 수 없음
서버에서는 인증받지 않은 클라이언트로부터 리소스를 숨기기 위해 403 대신 404 코드 전송 가능

5XX 서버 에러 응답

코드 메시지 설명
500 Internal Server Error 서버가 처리 방법을 모르는 상황과 마주침을 의미
서버에 문제가 있는 경우 사용하는 응답 코드

참고 사이트

저작자표시 (새창열림)