REST API #1 - 이해하기
REST Series
REST API
소프트웨어 엔지니링을 공부하다 보면 어느샌가 마주하는 녀석입니다.
모두가 얘기하고 대부분이 사용하지만 REST API 가 무엇인지, 왜 쓰는지에 대해 알고 설명할 수 있는 사람은 그렇게 많지 않습니다.
물론 저도 그 중 하나였고, 이 글을 통해 더 명확하게 REST API 에 대해 정의하고자 합니다.
이 글을 통해 REST API 의 개념과 어떻게 사용해야 하는지에 대해서 알아보고자 합니다.
1. REST API 란?
REST (REpresentational State Transfer) 란 웹를 사용할 때 제약 조건들을 정의하는 소프트웨어 아키텍처 스타일입니다.
우리가 흔히 쓰고 있는 월드 와이드 웹 (WWW) 의 창시자 중 한 명인 Roy Fielding 의 2000년 논문에서 소개 되었고, 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일입니다.
한국말 같지만 무슨 말인지 모르겠는 이 말을 정확하지 않지만, 이해하기 쉽게 설명한다면
HTTP 의 장점을 살리고자 하는 통신 규격
이렇게 얘기할 수 있습니다. 아직 감이 잘 안오시나요? 괜찮습니다. 우린 이제 이 글의 시작 지점이니까요. 아래에서 더 자세한 설명을 들어보죠.
1-1. 핵심 규칙
먼저 REST 에서 가장 핵심이 되는 규칙은
- URI 는 자원을 표현한다.
- 자원에 대한 행위는 HTTP Method 로 표현한다.
이 두 가지 규칙입니다. 이 두 가지 규칙만 준수해도 RESTFul 한 API 를 설계할 수 있습니다.
예를 들어 강아지 중 코난 이라는 강아지의 정보를 가져오는 메소드를 만들어 보겠습니다.
GET /pets/conan
Response
{
"name": "conan",
"age": 4,
"gender": "male"
}
첫 번째 규칙인 URI는 모든 자원을 표현한다, 위 예시의 경우 강아지인 코난 이라는 자원을 URI 로 표현했습니다. /pets/conan
두 번째 규칙인 자원에 대한 행위는 HTTP method 로 표현한다., 위 예시에선 정보를 가져오는 행위인 GET 를 사용했습니다.
어떤가요? 이런 핵심 규칙을 통해 REST 하게 API 를 설계할 수 있겠죠?
하지만 우린 좀 더 REST 세계로 딥다이브 해보겠습니다.
1-1. REST 의 기본 요소
REST 를 이루는 기본적인 요소는 다음 3가지입니다.
리소스 (Resource)
메소드 (Methond)
메세지 (Message)
세 가지 요소를 하나의 예를 통해 설명 드리겠습니다.
코난 이라는 이름을 가진 강아지 정보를 생성합니다. 라는 HTTP 요청이 있을 때,
리소스 - 강아지 정보 라는 리소스를 (Resource)
메소드 - 생성합니다. (Method)
메세지 - 그 이름은 코난..
탐정이죠(Message)
더 이해하기 쉽게 이를 REST 형식으로 표현해보겠습니다.
POST http://mypet/pets
{
"pets":{
"name": "코난"
}
}
이렇게 표현할 수 있겠네요.
어떤 것을 생성한다 (Create) 의 의미를 가진 HTTP POST 요청,
생성하려 하는 대상인 강아지라는 리소스는 http://mypet/pets 라는 URI,
생성하고자 하는 정보인 강아지의 이름은 JSON 방식으로 제공했습니다.
HTTP 메소드
위의 예시에서 이 포스팅에서 다루지 않은 개념이 등장하죠.
위 글을 읽는 분들은
HTTP POST 가 뭐에요?
라고 질문할 수 있습니다.
먼저 HTTP 는 우리 앞으로 웹에서 통신할 땐 이렇게 통신하자~ 라고 정의한 규칙입니다.
이 규칙 중엔 HTTP 요청을 크게 4가지 방식(Method) 으로 나눕니다.
| 방식 (Method) | 의미 | 역할 | |
|---|---|---|---|
| POST | Create | POST 를 통해 새로운 리소스를 생성합니다. | |
| GET | Select | GET 를 통해 해당 리소스를 조회합니다. | |
| PUT | Update | PUT 를 통해 리소스를 수정합니다. | |
| DELETE | Delete | DELETE 를 통해 해당 리소스를 삭제합니다. | |
| PATCH | Update | 리소스의 일부를 수정합니다. |
위 표에서 처럼 HTTP 요청 방식 (POST, GET, PUT, DELETE)은 각각 CRUD 에 대응됩니다.
표 맨 아래 PATCH HTTP Method 는 PUT 과 비슷하게 Update 라는 의미를 가지고 있지만, PUT 은 해당 자원 전체를 교체하라는 의미를 지녔지만, PATCH 는 자원의 일부를 변경한다는 의미를 가졌습니다.
때문에 최근엔 자원 전체를 업데이트하는 PUT 보다, 일부를 수정하는 PATCH 를 더 많이 사용하기도 합니다.
1-2 REST API 의 예시
이제 모든 기본 요소에 대해 이해 했으니, 하나씩 예시를 만들어 보겠습니다.
오늘 이 포스팅의 주인공인 코난..!
내 이름은 함정, 코난이죠
이 코난이 아닌 강아지 코난을 통해 REST API 예시를 설명해 보겠습니다.
댕댕이 코난
그럼 REST 한 CRUD API 를 생성해 볼까요?
1. 생성
이름이 conan, 나이가 3살 인 강아지 정보를 생성해줘
POST http://mypet/pets
{
"pets":{
"name": "conan",
"age": 3
}
}
http://mypet/pets 라는 리소스로 이름은 “conan”, HTTP POST 를 정의 했습니다.
이 요청은 코난 이라는 강아지 정보를 등록합니다.
2. 조회
이름이 conan 인 강아지 정보를 가져와줘
GET http://mypet/pets/conan
Response
{
"name": "conan",
"age": 3
}
이번엔 방금 생성한 코난의 정보를 가져왔습니다.
조회를 해야하기 때문에 HTTP Method 는 GET 방식을 사용 했고, URI 에 가져올 리소스인 강아지 정보 중 conan 를 특정했습니다.
3. 수정
conan 의 이름을 konan, 나이를 5살로 으로 변경해줘
PUT http://mypet/pets/conan
{
"name": "konan",
"age": 5
}
conan 의 이름을 konan 으로, 나이를 5살로 변경했습니다.
리소스를 수정해야 하기 때문에 HTTP Method 는 PUT 방식을 사용 했습니다.
4. 삭제
강아지 정보 중 konan 이란 이름을 가진 정보를 삭제해줘
DELETE http://mypet/pets/konan
Response 204
konan 의 정보를 삭제 했습니다.
이번엔 삭제를 해야하기 때문에 HTTP Method 는 DELETE 를 사용 했습니다.
2. REST 의 특성
지금까지 기본적인 개념에 대해 설명 했었는데, 이제 조금 더 상세하게 REST 에 대해 알아 보겠습니다.
상세한 내용은 위키에서 참고해서 가져왔습니다.
Client-Server Architecture
- REST API 에서 자원을 가지고 제공하는 측이 서버, 자원을 요청하는 쪽이 클라이언트에 해당합니다.
- 서버는 API 를 제공하고, 클라이언트는 사용자 인증, 세션, 로그인 정보를 관리하는 등 역할을 구분시킵니다.
- 역할 구분을 통해서 서로간의 의존성을 줄입니다.
Stateless (무상태성)
- 상태가 없다는 의미는 클라이언트의 Context, 세션과 같은 상태 정보를 서버에 저장하지 않음을 의미합니다.
- 서버에 클라이언트의 상태 정보를 저장하지 않으면, 요청에 대해 처리만 하면 되기 때문에 서버 구현이 단순해집니다.
Cacheable (캐시 가능)
- REST 는 HTTP 라는 기존의 웹 표준을 사용하기 때문에, HTTP 에서 사용하는 Last-Modified Tag, E-tag 를 통해 캐싱 구현이 가능합니다.
- 캐시를 통해 대량의 요청을 효율적으로 처리할 수 있습니다.
Layered System
- REST API 는 다중 계층으로 구성할 수 있고 LB, 암호화, Proxy 등 계층을 추가해서 구조를 변경할 수 있습니다.
- 클라이언트는 대상 서버에 직접 연결되었는지, Proxy 를 통해 연결 되었는지 알 수 없습니다.
Self-Descriptiveness (자체 표햔 구조)
- REST API 는 요청 메세지를 보고 이를 쉽게 이해할 수 있도록 자체 표현 구조로 되어 있습니다.
Uniform Interface (일관된 인터페이스)
- Resource 에 대한 요청으로 통일 되고, 한정적으로 수행하는 아키텍처 스타일을 의미합니다.
- 아키텍처를 단순화시키고 분리해 각 부분을 독립적으로 발전할 수 있습니다.
마지막으로
여기까지 REST 에 대해 개념과 예시를 통해 설명 드렸습니다.
REST 는 HTTP 프로토콜의 표준을 최대한 활용하면서 여러가지 장점을 극대화할 수 아키텍쳐 입니다.
다만 RESTFul 한 API 를 만들기 위해선 피해야할 패턴도 있고, 리소스의 정의에 대해 애매 모호한 부분도 있습니다.
다음 포스팅에선 이렇게 어려운 REST 디자인에 대해 실제 사례를 통해 더 실무적으로 설명 드리겠습니다.
이 글이 도움이 되셨으면 좋겠습니다.
감사합니다.