알림: 이 글은 개발자들이 프로그래밍을 작성할 때 남이 만들어놓은 라이브러리에 자기 코드를 덭붙이는 방식으로 내용을 작성했습니다. 즉, 다른 사람이 쉽게 설명 해놓은 것을 출처를 밝히며 복붙한 후, 제 설명을 덧붙이겠다는 말인데, 좀 더 우아하게 쓴 것입니다.
REST API란?
Representational State Transfer(이하 REST) 아키텍쳐를 갖춘 API.
깨알지식
REST 아키텍쳐는 Roy Fielding박사가 2000년에 자신의 박사학위 논문에 제안한 개념임. 당시 나이의 35살. 여러분들도 이런 논문 한번 내보는게 어떨까요?
필요한 지식:
Resource(리소스): REST에서 정보를 추상화한 것을 리소스라고 부름. 어떤 정보이든 이름을 붙일 수 있으면 리소스라고 부름. document, image, 객체 등.
Representation(표현): 클라이언트에게 리소스가 어떻게 보여지는지.
State (상태): "state란 당신이 실행 중인 프로그램에 의해 조작되고 반영된 데이터이다." 출처: https://bit.ly/3wfEuMg
Application State: 실행 중인 앱에 필요한 state.
Resource State: 서버에 저장된 리소스의 state.
Session State: User에 대한 정보. 서버에 저장됨.
출처:
REST아키텍쳐는 제약(조건)을 갖추어야 한다.
Uniform Interface 균일한 인터페이스
Stateless 스테이트리스
Cacheable 캐싱 가능성
Client-Server 독립
Layered System 계층구조적 아키텍쳐
Code on Demand (선택사항, 옵션)
Uniform Interface
웹/모바일 등 어떤 클라이언트가 API 요청을 보내든, API요청에 대한 리소스는 동일하게 보여져야 합니다.
- 리소스 식별: requsted된 리소스는 식별 가능하며, 클라이언트로 전송된 표현/데이터 (representation) 과는 분리되어야 함.
- Representation을 통한 전송 받은 데이터(Representation)에 충분한 정보가 있기 때문에, 클라이언트는 받은 데이터 (representation)을 가공할 수 있음.
- 클라이언트가 어떻게 메시지를 처리할지 메시지 자체로부터 어떤 메시지인지 유추 가능함.
- 하이퍼텍스트/하이퍼미디어가 가용가능함. 즉, 클라이언트가 리소스에 접근 후 하이퍼링크를 사용해서 "현재 수행 가능한 기타 모든 작업을 찾을 수 있어야 함." 출처: Red Hat Rest API
Stateless
클라이언트와 서버 간의 통신이 스테이트리스여야 함. 즉, 클라이언트가 서버에게 요청을 보낼 때, 각 요청 안에 서버가 요청을 이해하기 위한 모든 정보가 포함 되어야 함. 세션 정보는 고스란히 클라이언트한테 있음.
장점: 서버는 각 요청에 필요한 정보가 다 담겨 있기 때문에, request 외에 더 data를 찾을 필요 없음. 확장성이 늘어남.
Stateless vs Stateful
Stateless - 한번의 요청에 필요한 모든 정보가 전송 되고, 요청이 끝난 이후 전송 때 주고 받은 데이터를 저장하지 않음. 서버에 클라이언트 정보를 저장하지 않음. 이전 request와 상관 없음.
Stateful - 서버에 request에 대한 정보를 저장함. 이전의 request에 영향을 받음.
Cacheable
캐쉬란? 임시 저장소.
캐슁이란? 파일/데이터를 더 빨리 접속/열람하기 위해 저장하는 것. "가져오는데 비용이 드는 데이터를 한 번 가져온 뒤에는 임시로 저장하는 것". 웹에서는 인터넷 사이트를 더 빨리 띄우기 위해 HTML, javascript, 이미지 같은 파일은 웹 브라우저에 저장하는 것. CDN이 사용하는 개념.
Rest에서 캐슁 가능성이란, request에 의한 response 내용 안에 데이터가 캐슁 가능한지의 여부이며, (캐슁 되는지 안 되는지?), 캐슁이 가능하다면, 클라이언트는 이전에 사용한 캐쉬를 앞전과 같은 요청을 보낼 때, 즉, 같은 response를 받을 때재사용할 수 있음.
Client-Server 독립
클라이언트와 서버가 완전히 독립. 클라이언트와 서버가 완전히 독립하여, 각자 독립된 상태로 발전할 수 있음. 각자 독립된 상태로 발전해도, 서브/클라이언트 간 인터페이스는 유지해야 함.
Layered System 계층적구조
"REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 합니다." 출처: REST API 제대로 알고 사용하기
Code on demand (선택사항)
"REST API는 보통 정적 리소스를 전송하는데, 가끔은 java 애플릿과 같은 실행코드를 포함할 수 있음. 이런 경우 request시에만 실행."
출처: IBM Rest API
REST API의 특징.
각 요청이 어떤 동작이나 정보를 위한 것인지 요청 자체의 모습만으로도 유추할 수 있어야 한다.
REST API 설계 규칙
1. "URI는 정보의 자원을 표현해야 한다."
동사 사용 X, 명사 사용 O
전체 반의 명단을 가져오고 싶은 request 보낼 API를 작성한다고 가정해보자.
GET example.com/class/read
이렇게 동사로 이 API가 무엇을 하는지 보여주는 것이 아님.
GET example.com/class/
API가 달성하려는 것이 무엇인지는 앞의 HTTP 방식을 보고, 그리고 그 방식이 실행되는 주체는 뒤에 명사를 보고 유추함.
이렇게 쓰여져 있으면, 반 전체의 명단을 가져오라고 유추할 수 있음.
GET example.com/class/1
반 뒤에 index 번호가 이렇게 적혀 있으면, 전체 반에서 '1반'을 요청하는 구나 라고 알 수 있음.
{
"result": [
{"idx": 1, "name": "1반"},
{"idx": 2, "name": "2반"},
{"idx": 3, "name": "3반"},
]
}
GET example.com/class/1/students
이렇게 적혀 있으면, 1반의 학생 명단을 요청하는구나 라고 알 수 있음.
{
"result": [
{"idx": 1, "name": "홍찬양"},
{"idx": 2, "name": "은지김"},
{"idx": 3, "name": "진호장"},
]
}GET example.com/class/1/students/3
이렇게 적혀 있으면 1반의 3번 학생을 요청하는 구나 라고 알 수 있음.
POST, DELETE, PUT, PATCH 다 동일하게 적용 됨.
스프링에서의 예시.
API URI 설계시 주의 점
1. '/'는 계층 관계를 나타내는데 사용.
https://www.example.com/countries/cities/towns
https://www.example.com/schools/classes/students
2. URI의 마지막 문자로 '/'를 포함하지 않는다.
https://www.example.com/countries/cities/towns O
https://www.example.com/countries/cities/towns/ X
3. 밑줄 '_'가 아닌 대쉬 '-' 사용.
긴 URI에서 불가피하게 특수문자 '-' 사용해야 한다면, 가독성을 위해서 '-'를 사용.
https://career.guru99.com/category/heavy-industries/
4. URI는 소문자 사용.
5. REST API에서는 HTTP Method의 GET, POST, PUT, DELETE, PATCH (option)을 사용함.
* Roy Fielding은 이런 말 한적 없음. 어쩌다가 변질 되어버림.
GET - read,
POST - create,
DELETE - delete,
PUT - 정보를 통째로 수정할 때,
PATCH - 정보 중 특정 부분을 수정할 때.
이름: 호성우,
성별: 남자,
팀: 1 - > 2 로 수정할 때.
위에서 언급 했듯이, 방식만 보고 API가 무엇을 하려는지 알 수 있어야 하기 때문에, HTTP METHOD를 정확하게 써야 함.
예) POST로도 read할 수 있지만, 그러면 구조만 보고 API가 무엇을 달성하려는지 알 수 없기 때문에 GET을 사용하는 것.
참고자료:
쉽고 한번에 이해하고 싶다면
REST 아키텍쳐에 대한 설명
https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
REST API에 대한 설명
https://www.ibm.com/kr-ko/cloud/learn/rest-apis
https://www.redhat.com/ko/topics/api/what-is-a-rest-api
https://meetup.toast.com/posts/92
REST API 설계에 대한 설명
https://meetup.toast.com/posts/92
https://spoqa.github.io/2012/02/27/rest-introduction.html