[Web/Theory] REST API

REST API란?

---

Representation State Transfer (표현 상태 전이, REST)

REST API는 세 가지로 구성되어 있다.

1. 자원(Resource) : URI를 이용해 자원을 나타낸다. 예를 들어, '사용자'라는 자원이라면 http://pangtrue/users/와 같이 나타낼 수 있다.
2. 행위(Verb) : HTTP  METHOD를 이용한다. 예를 들어, '생성한다'라는 행위라면 HTTP POST를 사용한다.
3. 표현(Representation) : JSON 형식으로 나타낸다. 예를 들어, '이름이 ted인 사용자'라면 다음과 같이 표현한다.

{
  "users" {
    "name": "ted"
  }
}

 

 

 

REST의 특징

---

REST는 6가지의 특징을 가진다.

1. Uniform
   Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다.
2. Stateless (무상태성)
   상태 정보를 따로 저장하거나 관리하지 않는다. API 서버는 들어오는 요청을 단순히 처리하면 되기 때문에 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.
3. Cacheable
   REST의 가장 큰 특징은 HTTP라는 웹 표준을 사용한다는 것이다. 덕분에 HTTP가 가진 캐싱 기능을 사용할 수 있다.
4. Self-descriptiveness (자체 표현 구조)
   REST API 메시지만 보고도 쉽게 이해할 수 있는 자체 표현 구조를 가진다.
5. Client-Server 구조
   REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 토큰, 로그인 정보)를 직접 관리하는 구조로 각각의 역할이 구분되기 때문에 서버와 클라이언트에서 개발해야할 내용이 명확해지고 서로간의 의존도가 낮아진다.
6. 계층형 구조
   REST 서버는 다중 계층으로 구성될 수 있다. 예를 들어, 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 확보할 수 있고 프록시나 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수도 있다.

 

 

 

REST API 설계

---

REST API 설계 시 가장 중요한 체크 항목은 두 가지다.

1. URI는 어떤 자원인지를 표현해야 한다.
2. 자원에 대한 행위에 알맞는 HTTP Method(GET, POST, PUT, DELETE)를 선택해야 한다.

 

HTTP Method별 올바른 행위는 다음과 같다.

METHOD	행위
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성한다.
GET	리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	리소스를 수정한다.
DELETE	리소스를 삭제한다.

 

URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP METHOD를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.

 

 

 

URI 설계 시 주의할 점

---

URI를 설계할 때 주의해야할 점은 다음과 같다.

1. 슬래시 구분자(/)는 계층 관계를 나타내는데 사용한다.
   예1) http://restapi.example.com/houses/apartments
   예2) http://restapi.example.com/animals/mammals/whales
2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
   URI는 리소스의 유일한 식별자로 사용되어야 한다. URI의 마지막에 슬래시(/)가 없는게 리소스를 표현한다는 의미상 더 적합하다.
3. 하이픈(-)은 URI의 가독성을 높이는데 사용할 수 있다.
   여러 단어가 들어가야 한다면 하이픈을 사용해 가독성을 향상시킬 수 있다.
4. 밑줄(_)은 URI에 사용하지 않는다.
   글꼴에 따라 차이가 있긴 하지만, 대개 밑줄은 보기 어렵거나 밑줄로 인해 문자가 가려질 수도 있다. 밑줄 대신 하이픈을 사용하자.
5. URI 경로에는 소문자가 적합하다.
   대소문자에 따라 다른 리소스로 인식되기 때문에 URI에 대문자 사용은 피해야 한다. (RFC 3986 - URI 문법 형식)
6. 파일 확장자는 URI에 포함시키지 않는다.
   URI에 직접적으로 파일 확장자를 포함시키는 대신 Accept header를 사용한다.
   GET / members/baseball/10/photo  HTTP/1.1  Host: restapi.example.com  Accept: image/jpg

 

 

 

HTTP 응답 상태 코드

---

잘 설계된 REST API는 URI만 잘 설계된 것이 아니라 리소스 request에 대한 response 또한 정확해야 한다. response의 상태 코드만으로도 많은 정보를 나타낼 수 있기 때문에 어떤 상태 코드를 반환할지를 세심하게 살펴야 한다.

 

 

 

참고자료

---

[1] https://hyunalee.tistory.com/1?category=575773

[2] https://meetup.toast.com/posts/92