Concept: REST API의 기본 개념 이해와 활용

REST API의 기본 개념 이해하기

REST(Represented State Transfer) API란?

---

REST란 HTTP(웹)의 장점을 최대한으로 활용할 수 있도록 제시된 아키텍처입니다. 기본적으로 제공되는 HTTP 메서드들을 규칙에 알맞게, 바람직하게 사용하는 것이죠. 다른 말로 하면, 자원을 URI로, 행동을 메서드로 잘 표현하여 요청과 응답을 정의하는 방식입니다.
무엇을 하고 있는지, 어떤 것에 대한 대화인지를 HTTP 요청/응답 메시지를 보고 파악할 수 있도록 하는 것이죠!

REST API의 제한 조건

---

6가지의 제한 조건이 존재합니다. 설명에 앞서서 무엇들이 있는지 요약해보는 것이니 이해되지 않아도 괜찮습니다. 가볍게 훑어보시고 설명을 담고 있는 아래 문단으로 넘어가시죠!

1. 인터페이스 일관성
2. 무상태성 : 세션은 컨텍스트를 저장하지 않는다.
3. 캐시 처리 가능 : HTTP가 지원하는 기능을 통해 캐싱할 수 있다.
4. 계층화
5. Code on demand
6. 클라이언트/서버 구조

• 위 제한조건 내용은 위키백과 - REST를 참고했습니다.

REST API 규칙

---

보통 6가지 or 7가지 네이밍 규칙을 많이 소개해주고 있는데 조금만 설명을 덧붙여보려고 합니다.

1. URI는 자원을 표현하되 동사 보다는 명사를 사용합니다. : GET /members/delete/1
2. 자원에 대한 행위는 HTTP Method로 표현합니다. : DELETE /members/1, POST /members/2. 참고로 각 메소드에 대한 역할은 다음과 같습니다. 각각은 CRUD를 대표합니다.
   1. POST : 리소스를 생성합니다.
   2. GET : 리소스를 조회하거나 데이터를 가져옵니다.
   3. PUT : 리소스를 수정합니다. (본래 의미는 파일은 전송하는 method지만, 웹끼리 연계하는 REST api 안에서는 이런 의미입니다. HTTP/1.1 상에서는 기본적인 인증기능을 요구하지 않는 method기 때문에, 필요하다면 인증 기능은 어플리케이션과의 연계로 해결해야 합니다)
   4. DELETE : 리소스를 삭제합니다. (PUT과 마찬가지로 본래 의미는 파일을 삭제하는 것이고, HTTP/1.1 상에서 인증기능이 없습니다.)
3. 슬래시/는 계층관계를 나타낼 때 사용합니다. : /animals/mammals/humans
4. URI 마지막에 슬래시를 사용하지 않습니다. : 잘못된 경우의 예시 /animals/mammals/humans/
5. 단어와 단어는 카멜케이스나 스네이크케이스를 사용하지 않고 하이픈-으로 연결합니다.
6. 소문자를 사용합니다.
7. URI에 확장자를 포함시키지 않습니다.
8. 리소스 간 연관관계를 표현할 때 :
   1. 소유(has) 관계를 표현할 때의 예시 : GET : /users/{userid}/devices
   2. 소유 관계이면서 더욱 구체적인 표현이 필요할 때의 예시 : GET : /users/{userid}/likes/devices
9. 복수로 표현할 수 있는 것은 복수로 표현합니다. 하지만 좀 더 실사용적인 예를 덧붙이자면, 도큐먼트는 단수, 도큐먼트의 그룹은 복수로 표현합니다.
10. 적절한 상태 코드가 무엇일지 고려하여 응답해야 합니다! : REST는 요청에 대한 명세가 아니라 요청과 응답에 대한 명세임을 기억하며 사용합니다.

• 위의 조건들은 여러 웹문서를 참고하였으나, 특히 예시들은 NHN Cloud Meetup의 포스트를 참고하였습니다.

REST 성숙도 - REST API는 호락호락하지 않다

---

REST API는 표현방식이나 설계에 있어서 위에 말한 것들과 같은 여러 규칙을 제시하는데요.
사실 이 가이드들을 다 지키기에는 꽤나 엄격한 터라 지키기가 쉽지 않다고 해요. 또 HTTP 규약 자체도 완전히 완벽한 것은 아니니까요. 그래서 실무를 하다 보면, 적절히 trade-off 하는 것이죠.

그래서인지 REST를 얼마나 잘 지키고 있다고 말할 수 있는지, 성숙도를 구분하는 단계가 나누어져 있습니다.
정확히 말하자면, REST 개념을 처음 이야기 한 로이 필딩 박사가 제시한 것은 아니고 레오나르도 리차드슨이란 분이 제시한 단계지만요.

• 0단계 - HTTP 사용 : HTTP를 사용하는 것이 REST의 첫걸음이다...라는 느낌이지만 이것만으론 RESTful하다고 할 수 없겠죠.
• 1단계 - 개별 리소스와의 통신 준수 : 모든 데이터나 자원을 URI로 표현한다고 위에서 말했는데요. 각각의 엔드포인트, 그러니까 URI 하나 하나가 각각의 데이터나 자원을 전달해야해요. 예를 들어 /posts/newest라는 엔드포인트에서 전달되는 엔티티에 따라서, 어떤 때는 모든 유저가 작성한 새로운 포스트 데이터, 어떤 때에는 새로운 포스트가 올라온 시간 등 다른 자원을 전달한다면 그건 1단계에 어긋난다고 볼 수 있겠죠.
• 2단계 - 적절한 HTTP Request method 사용 : 모든 요청을 GET으로만 써서 통신을 할 수도 있겠죠. 하지만 값을 입력할 때에도, 업데이트 할 때에도, 삭제할 때에도, 확인할 때에도 GET만 사용한다면 그건 2단계를 준수하지 않는 것입니다. POST와 PUT, DELETE 등의 메소드들을 적절히 사용해야 해요. HTTP 메소드를 잘 지켜서 사용하기 때문에 이 단계까지 지키는 것을 HTTP API라고 엄격히 나누는 분들도 계세요.
• 3단계 - HATEOAS(Hypertext As The Engine Of Application State) 준수 : 이름도 참 길죠? 2단계와 동일하지만, 응답 메시지의 이야기에요. 응답에는 자원의 URI를 포함한 '링크' 요소들을 추가해서 작성한다는 점이죠. 쉽게 말해 /posts라는 엔드포인트를 조회했다면, '해당 포스트를 보고 싶다면 ~~한 uri에 GET 요청을 날려. 또, 해당 포스트를 삭제하고 싶다면 @@라는 uri에 DELETE 요청을 날려'와 같은 부가 정보를 덧붙여서 돌려주는 거에요.

REST 독재자가 되지는 말자

---

REST가 좋은 의도로 나온 설계 개념인 것은 맞습니다.
하지만 환경과 요구사항에 알맞게 실사용할 수 있도록 충분히 고려하여 설계하는 것이 더욱 중요합니다.
REST를 공부하는 이유는 고려하는 단계에서 충분히 여러가지를 고려하도록, 그리고 다른 사람에게 REST를 설명할 수 있기 위해서 등등의 이유라는 것을 잊으면 안되겠습니다.