REST API
REST API
REST(REpresentational State Transfer)
로이 필딩(Roy Fielding)의 2000년 논문에서 처음 소개되었으며,
발표 당시의 웹이 HTTP의 설계 상 우수성을 제대로 사용하지 못하고 있는 상황을 보고
웹의 장점을 최대한 활용할 수 있는 아키텍쳐로서 REST를 제시REST는 HTTP 프로토콜을 의도에 맞게 디자인하도록 유도하며,
REST의 기본 원칙을 성실히 지킨 서비스 디자인을 "RESTful"하다고 표현
1. REST API 속성
- 서버에 있는 모든 자원은 각 자원당 클라이언트가 바로 접근할 수 있는 고유 URI가 존재
- 모든 요청은 클라이언트가 요청할 때마다 필요한 정보를 주기 때문에 서버에서는 세션 정보를 보관할 필요가 없음
→ 서비스 자유도가 높아지고 유연한 아키텍쳐 적용이 가능 - HTTP 메서드 사용
자원에 대한 행위는 GET, POST, PUT, DELETE 등의 HTTP Method로 표현 - 서비스 내에 하나의 자원이 주변에 연관된 자원들과 연결되어 표현되어야 함
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 | 서버가 처리 방법을 모르는 상황과 마주침을 의미 서버에 문제가 있는 경우 사용하는 응답 코드 |