REST API 원칙

REST API란?

---

REST는 Representational State Transfer라는 용어의 약자로서 로이 필딩의 박사학위 논문에서 처음 등장하였다.

로이 필딩은 웹(http) 설계의 우수성에 비해 제대로 활용되어지지 못하는 모습에 안타까워하며 웹의 장점을 최대한 활용할 수 있는 아키텍처로써 REST를 발표했다.

 

REST API 디자인 가이드

---

REST API 설계 시 가장 중요한 항목은 다음 2가지로 요약할 수 있다.

 

1. URI는 정보의 자원을 표현할 수 있어야 한다.

2. 자원에 대한 행위는 HTTP method(GET, POST, PUT, DELETE)로 표현한다.

 

ex1) 

GET/members/delete

위와 같은 표현은 REST API 설계 규칙을 적용하지 않은 표현이다. URI는 자원을 표현해야 한다. delete와 같은 행위가 들어가서는 안된다. 대신에,

 

DELETE/members

처럼 설계 규칙을 적용하여 표현할 수 있다.

 

 

[HTTP METHOD의 roles]

METHOD	역할
GET	GET을 통해 리소스를 조회한다. 리소스를 조회하고 해당 다큐먼트에 대한 정보를 가져온다.
POST	POST를 통해 URI를 요청하면 리소스를 생성한다. (ex : 새로운 회원 생성)
PUT	PUT을 통해 URI를 요청하면 리소스를 수정한다.
DELETE	DELETE를 통해 리소스를 삭제한다.

 

즉, URI는 자원 자체를 표현하는데 중점을 두고 행위에 대한 정의는 METHOD를 통해 구분지어주는 것이 좋다.

 

REST API 설계 시 주의할 점!

---

1. 슬래시 구분자는 계층관계를 나타낸다.

localhost/animals/mammals

localhost/animals/mammals/dogs

2. URI 마지막에 슬래시(/) 구분자를 포함하지 않는다.

URI에 포함되는 모든 글자는 리소스의 식별자로 사용돼야 한다. REST API는 분명한 URI를 만들어 통신을 해야하기 때문에 혼동을 주지 않도록 URI의 마지막 경로에는 슬래시(/)를 사용하지 않는다.

 

3. 언더바(_) 대신 하이폰(-)을 사용한다.

URI를 쉽게 읽고 해석하기 위해 언더바(_) 대신 하이폰(-)을 사용한다.

 

4. URI 경로에는 소문자를 사용한다.

URI는 대소문자에 따라 다른 URI로 판단하기 때문에 소문자로 통일시켜준다.

 

5. 파일 확장자는 URI에 포함시키지 않는다.

 

HTTP 응답상태 코드

---

잘 설계된 REST API는 URI 뿐만 아니라 그 리소스에 대한 응답 또한 잘 전달해주어야 한다.

정확한 응답의 상태코드만으로도 많은 정보를 전달할 수 있기 때문에 응답의 상태코드를 명확히 전달하는 것은 RESTful한 API 설계를 위해서 중요한 요소라고 할 수 있습니다.

상태코드
200	클라이언트의 요청을 정상적으로 수행함
201	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST의 경우)

 

상태코드
400	클라이언트의 요청이 부적절한 경우
401	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 경우
403	유저 인증상태와 상관없이 응답하고 싶지 않은 리소스를 요청했을 경우(403보다는 400이나 404 사용을 권고. 403 자체가 리소스가 존재한다는 뜻)
405	클랑이언트가 요청한 리소스에서는 사용불가능한 METHOD를 요청했을 경우

 

상태코드
301	클라이언트가 요청한 리소스에 대한 URI가 변경되었을 때 사용하는 응답 코드
500	서버에 문제가 있을 경우

 

p.s 현재 react native와 node express를 통해 REST API를 구축해서 개발을 진행중이다. 프로젝트를 계속 진행하면서 REST API의 좀 더 심화적인 부분을 접해볼 예정이다.