[Web] RESTful API

REST API에 대해 정리해보자 😁

 

 

 

1. API

---

API는 Application Programming Interface(애플리케이션 프로그래밍 인터페이스)의 약자로 어떠한 응용프로그램에서 데이터를 주고 받기 위한 방법 또는 규칙을 의미한다.

클라이언트와 서버 간 데이터를 주고받을 때로 예로 들면, 어떠한 방식으로 정보를 요청해야 하는지 어떠한 데이터를 전달받을 지에 대한 규격을 말한다. 규격을 표준화해놓으면 여러 서비스에서도 쉽게 데이터를 요청하고 사용할 수 있다.

 

요즘 대형 플랫폼에서는 누구나 사용할 수 있게 만든 OpenAPI를 제공한다. 내가 만들고 싶은 사이트에 소셜 로그인 기능과 날씨 정보가 필요하다면 직접 구현하지 않아도 네이버, 카카오 등의 로그인 API과 기상청 API를 이용해 여러 서비스에서 쉽게 사용할 수 있다. 

 

 

 

2. REST

---

 

 

출처 : cloudinary

 

 

REST(REpresentational State Transfer)란

웹의 장점을 활용할 수 있는 아키텍처로

1. HTTP URI를 통해 자원(Resource)을 명시하고
2. 자원에 대한 행위를 HTTP Method(GET, POST, PUT, DELETE, PATCH 등)로 표현해
3. 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다.
   (POST: 생성, GET: 조회, PUT: 수정, DELETE: 삭제 등)

 

 

REST 특징

• 클라이언트-서버 구조 (Client-Server)
  • 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보)등을 직접 관리하고, 서버는 REST API를 제공하는 구조로 각각의 역할이 구분된다.
  • 서로 간에 의존성이 줄어든다.
• 무상태성 (Stateless)
  • REST는 HTTP를 이용하기 때문에 무상태(Stateless) 특성을 갖는다.
  • 클라이언트의 컨텍스트를 서버에 저장하지 않는다.
  • 서버는 각각의 요청을 별개의 것으로 인식하고 처리한다.
• 캐시 처리 가능 (Cacheable)
  • 캐싱 기능을 갖는 HTTP의 특성을 이용하기 때문에 REST도 역시 캐싱 기능을 적용할 수 있다.
  • 대량의 요청을 효율적으로 처리할 수 있다.
• 자체 표현 구조 (Self-descriptive)
  • REST API 자체만으로 해당 요청이 어떤 자원으로 어떤 행위를 하는지 알 수 있다.
• 일관된 인터페이스 (Uniform)
  • URI에서 지정한 리소스에 대한 행위를 통일되고 한정적인 인터페이스로 수행한다.
  • HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.

 

 

 

3. REST 규칙

---

REST 원칙을 올바르게 설계하기 위해서는 몇가지 규칙이 있다.

 

• HTTP URI를 통해 자원(Resource)을 명시
  • 자원을 명시할 때 동사보다는 명사를, 대문자보다는 소문자를 사용한다.
  • URI에 행위에 대한 동사 표현을 포함시키지 않는다.
    GET /users/search (x)
GET /users (o)
  • URI에 변하는 부분은 유일한 값으로 대체한다.
    GET /users/{id} (o)
• 자원에 대한 행위를 HTTP Method로 표현 (하단 표 참고)
  • URI에 HTTP Method를 포함시키지 않는다.
    DELETE /users/delete/{id} (x)
DELETE /users/{id} (o)
• 마지막에 슬래시(/)를 포함하지 않는다.
• 언더바(_)대신 하이픈(-)을 사용한다.
• 파일 확장자는 URI에 포함하지 않는다.

 

 

행위에 대한 정의는 URI에 명시하는 것이 아닌 HTTP Method로 표현한다고 했는데, 각 Method가 어떤 행위를 요청할 때 사용하는지 확인해보자.

 

METHOD	역할
GET	리소스 조회
POST	리소스 생성
PUT	리소스 수정
PATCH	리소스 일부 수정
DELETE	리소스 삭제

 

PUT은 리소스의 필드 여러개를 수정하는 경우, PATCH는 리소스의 필드 일부를 수정하는 경우 사용한다. 예를 들어, 마이페이지에서 사용자 정보를 변경할 때 이름, 전화번호, 이메일을 한번에 변경하는 경우 PUT요청을, 프로필 이미지만 변경하는 경우 PATCH요청을 한다.

 

 

나는 실무에서 이 규칙들을 대부분 적용해 API를 설계했다. 그렇지만 무조건적으로 따르지 않고 상황에 따라 유연하게 바꾸기도 했다.
예를 들어, 특정 조건에 부합한 책(/books)을 조회하는 경우 GET요청이 아닌 POST요청으로 구현했는데, GET 요청을 사용한다면 조회 조건이 많아졌을 때 URI길이를 예측할 수 없기 때문이다. 따라서 body에 조회 조건을 담아 POST로 요청하고, 조회하는 API임을 URI에 명시해줬다.
ex) POST : /books/search-condition

 

 

HTTP 응답코드

상태코드	설명
2xx	클라이언트 요청이 성공적으로 완료
4xx	클라이언트의 잘못된 요청
3xx	클라이언트는 요청을 완료하기 위해 추가행동을 취해야 함
5xx	서버 오류

 

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 요청에 대한 응답을 잘 내어주는 것까지 포함된다. client는 응답코드에 따라 처리하는 동작이 달라지므로, 각 상태에 명확한 응답코드를 전달해야 한다.

 

 

 

4. RESTful API

---

RESTful이란 REST라는 아키텍처를 따르는 시스템을 나타내기 위해 사용되는 용어이다. REST의 설계 규칙을 올바르게 지킨 시스템을 RESTful하다 말할 수 있다.

 

정리하면, REST가 아키텍처 스타일 및 인터페이스이고, REST를 지켜 구현된 API를 RESTful API라고 말하는 것이다.

 

RESTful한 API를 구현해 여러 시스템에서 정해진 규칙으로 데이터를 쉽게 주고 받을 수 있는 장점이 있지만, 각 시스템마다 추구하는 우선순위가 다르므로 예외규칙을 정한다면 RESTful한 API를 유연하고 다양한 방법으로 구현할 수 있을 것이다.

 

참고자료 😃

https://hahahoho5915.tistory.com/54

https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

https://meetup.nhncloud.com/posts/92

https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html