-
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 서버가 처리 방법을 모르는 상황과 마주침을 의미
서버에 문제가 있는 경우 사용하는 응답 코드
참고 사이트