간단하게 말하자면, 통신 간에 안전한 정보의 교환을 위해 사용하는 API라고 말할 수 있다.
우선 API가 무엇인지부터 알아보자.
API
Application Programming Interface의 약자로, 다른 소프트웨어 시스템과 통신하기 위해 따라야 하는 규칙이다. 예를 들자면, 식당의 메뉴판을 생각하면 된다. 우리는 식당에 가서 우선 메뉴판을 보고 어떤 음식들을 주문할 수 있는지, 가격은 얼마인지, 양은 얼마인지 파악하고 이를 토대로 주문을 한다. 이와 같이 API를 통해 특정 데이터를 요청하고 응답받는 것에 대해 미리 그 규칙을 정한것이라고 생각할 수 있다.
그렇다면 RESTful 하다는 것은 무엇일까?
RESTful
글자 뜻 그대로 REST-ful, 즉 REST하다는 것을 의미하는데, 여기서 REST는 Representational State Transfer의 약자로, API가 작동하는 방식에 대한 조건을 부여했다고 생각할 수 있다. AWS에서 제공하는 설명을 보면 REST 기반 아키텍처를 사용하여 대규모의 고성능 통신을 안정적으로 지원할 수 있다고 나와있다. 우선 쉽게 음식점에 간 상황을 예로 들어보자. 예를 들어서 우리가 고깃집에 갔을 때, 만약 메뉴가 돼지고기, 소고기, 식사 이렇게 세가지만 존재하고 그 가격도 양도 어떠한 구성도 모르는 상황이라면, 우리는 음식을 주문하는데 오랜시간이 걸리고, 심지어는 식당을 나올 수도 있다. 때문에, 만약 그 고기의 종류가 매우 많은 경우라면, 보통 메뉴판에 여러가지 부위에 대한 가격과 무게등이 표시되어 손쉽게 주문을 완료할 수 있다.
RESTful API란 이와 같은 맥락으로, 만약 CRUD에서 Create에 해당하는 부분을 단 하나의 POST요청으로만 정의하고 처리한다면, 대규모의 서비스에서는 매우 많은 에러와 혼란과 솔직히 서비스가 불가능할 것이다. 때문에, 요청 및 응답별로 여러 조건을 구분지어서 데이터의 종류에 따라 적합한 요청과 응답을 하도록 그 조건들을 정한 API라고 볼 수 있다.
그렇다면 REST API를 어떻게 작성해야 할까?
REST 구성 요소와 기본 규칙
REST를 이루기 위해선, REST를 구성하는 요소와 이에 대한 규칙들을 지켜야 한다.
URI는 정보의 자원을 표현해야 한다.
자원을 다루는 것은 HTTP Method로 표현해야 한다.
1번의 경우 정보의 자원을 표현해야 한다는 의미는 자원 자체를 표현하는 것을 지향하고, 자원을 얻는 행위 등의 표현을 지양해야 한다는 의미이며, 2번의 경우 자원을 다루는 행위에 적합한 HTTP Method를 사용해야 한다는 의미이다.
// bad
GET /getTodo/1
GET /todos/delete/1
// good
GET /todos/1
DELETE /todos/1예시와 같이 좋지 않은 API는 정보의 자원을 표현할 때, 목적하는 자원에 행위가 포함되거나 삭제하는 상황에서 DELETE 메서드가 아닌 GET메서드를 사용하고 있다. 이와 같이 REST를 구성하기 위해서는 위의 규칙들을 지켜서 작성하는 것이 바람직하다.
REST는 총 3가지로 구성된다.
- 자원(Resource) -> HTTP URI
- 자원에 대한 행위(Verb) -> HTTP Method
- 자원에 대한 행위의 내용(Representations) -> HTTP Message payload
자원(Resource)
HTTP URI이 자원에 해당하는데, URI는 웹 서비스에서 자원을 식별하는 데 사용되는 개념이다. 이 URI를 통해 자원의 정보를 표시해야 한다. 이떄, 지켜야 할 규칙은 다음과 같다.
- 자원에는 동사보다는 명사를 사용하며, 소문자를 사용해야 한다.
- 자원의 도큐먼트 이름으로는 단수 명사를 사용해야 한다.
- 자원의 컬렉션 이름으로는 복수 명사를 사용해야 한다.
- 자원의 스토어 이름으로는 복수 명사를 사용해야 한다.
GET /todo/1 -> GET /todos/1자원에 대한 행위(Verb)
자원에 대한 행위로 HTTP Method를 사용한다. 즉, 우리가 알고 있는 GET, POST, PUT, PATCH, DELETE를 말한다.
- URI에는 HTTP Method가 들어가면 안된다.
- URI에 동사 표현(CRUD)이 들어가면 안된다.
- URI중 변하는 부분은 유일한 값으로 대체한다.
GET /todos/delete/1 -> DELETE /todos/1
GET /todos/show/1 -> GET /todos/1
GET /todos/add/2 -> POST /todos/2이외에도 작성 시에 지켜야 할 규칙들이 몇가지 있다.
REST API 작성 규칙
슬래시(/)는 계층 관계를 나타내기 위해 사용한다.
http://sample.todo.com/todos/monthsURI의 마지막에 슬래시(/)를 포함하지 않는다.
http://sample.todo.com/todos/months/ -> bad
http://sample.todo.com/todos/months -> good하이픈은 가독성을 위해 사용한다.
http://sample.todo.com/todos/weekly-todo언더스코어는 사용하지 않는다.
http://sample.todo.com/todos/weekly_todo -> bad파일확장자는 Accept Header로 표시한다.
http://sample.todo.com/todos/weekly-todo/1/photo.jpg -> bad
GET/ todos/weekly-todo/1/photo HTTP/1.1 HOST: sample.todo.com Accept: image/jpg -> goodURI에 버전 정보를 포함시킨다.
GET /v1/todos
// API 업데이트가 발생했다면,
GET /v2/todos글을 마무리 하며
오늘은 REST API에 대해 알아보았다. REST API는 독립적으로 작동되는 클라이언트와 서버간의 통신에 있어서 안정적이고 효율적인 통신을 가능하게 해주는 필수적인 역할을 한다. 물론, REST API에 있어서, 표준이 존재하지는 않지만, 어느정도 일반적으로 통용되는 규칙들을 알아보았다. 이전의 협업에서도 주로 백엔드 엔지니어 분들께서 API 문서 작성을 하셨지만, 프론트엔드도 소홀히하면 안되는 부분임을 아는 만큼 이번 블로깅에 정성을 쏟은 것 같다. 작성을 완료하는 시점에서 부족한 점이 많다고 생각되므로, 이후 실제 작성을 하게 되면 수정을 하거나 업데이트를 하게 될 것 같다.
Reference
