[Web] REST API이란

유저 인증이나 요리 리스트 등 데이터를 통신하기 위해서 우리는 API 를 구성한다. API 는 백엔드에 있어서 서비스 로직이 가장 많이 들어가는 부분이기도 하다. 간단히 구성을 알아보자.

REST API 란?

REST(Representational State Transfer) API 란 데이터를 통신함에 있어 이름 등을 지정해서 리소스의 상태를 통신하는 방식을 의미한다. 주로 json 을 이용한 포멧으로 사용한다. 이 방식에는 몇가지 규칙이 있다.

1. HTTP URI(Uniform Resource Identifier)를 통해서 자원을 표현한다.
2. HTTP Method(GET, POST, …) 를 이용한다.
3. 이 방식을 통해서 자원(URI)에 대한 CRUD 를 실행한다.

처음에는 규칙이 다 상관이 없는 것 같은데 사실은 이어져 있다. 1번은 어떤 자원을 이용할 것인지 정의하고, 2번은 어떤 액션을 할건지 정의하고, 3번은 1,2번을 통해서 실제 DB에 반영 내용을 의미한다. HTTP 프로토콜을 그대로 사용하기 때문에 별도로 인프라 구축이 필요없고 대부분의 플랫폼에서 이용가능하다. 하지만, 표준이 없기 때문에 정의를 해야하고, 구형 브라우저에서는 사용하지 못하는 문제, Method 가 제한적이라는 단점이 있다. 이외의 리소스의 상태를 코드로 나타내는데, 그 유명한 404, 200 OK가 여기에 포함된다.

RESTful API 란?

간혹 면접을 볼때 REST API 와 RESTful API를 묻는 경우가 있는데, RESTful 이라는 이름과 같이 REST API 를 이용하는 서비스(시스템)을 의미한다. 단순히 REST API 가 잘 정의되어있다면 RESTful 하다 라고 말하는 것이다.

REST API 실전 적용!

1. URI 컨벤션

URI 를 정의할 때 기초적으로 알려진 몇가지 컨벤션이 있다.

• 동사보단 명사로

  POST /documents/new (X)
  POST /documents (O)
  

  POST 메소드가 이미 생성의 의미를 가지고 있어 new를 사용하는 것은 이상하다. (의미 중복)

• 리소스는 복수로

  POST /document (X)
  POST /documents (O)
  

• _ 대신 - 로 작성

  POST /users/sign_in (X)
  POST /users/sign-in (O)
  

• 행위(method)는 작성하지 않는다.

  POST /document/post (X)
  POST /document (O)
  

이 글을 읽어보는 것을 추천한다.

Best Practices for Designing a Pragmatic RESTful API

2.METHOD 알아가기

위 URI 컨벤션에서 이미 이야기한 내용도 있지만, API에서 METHOD는 각각 의미를 가지고 있는데, 우선 Method 로는 GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 등이 있다. (CONNECT, TRACE 라는 것이 있긴한데… API에서 주로 사용하지는 않는다.)

• GET : 특정 리소스를 조회, 가져오기 (list, detail(단일 리소스))

• POST : 리소스 생성-수정

• PUT : 리소스 수정 하지만, 정의하지 않은 값은 default 값으로 업데이트

• PATCH : 리소스의 특정 부분만 수정, PUT과 달리 정의하지 않은 값은 업데이트 하지 않는다.

• DELETE : 리소스 제거

• HEAD : GET과 동일하지만, 헤더 정보만 응답하는 메서드(리소스 바디가 존재하지 않음)

• OPTIONS : 해당 엔드 포인트에서 사용할 수 있는 Method를 응답합니다. 하지만, 요즘은 swagger 등으로 api 문서를 자동화해두어서 options를 이용하는 일이 변로 없긴합니다..

여기서 HEAD와 OPTIONS는 리소스의 대한 정의가 아니고 대체할 수 있는 것들이 많기 때문에 크게 중요하지 않다.

METHOD 특징들…!

안정성

안정성이란 실제 리소스에 영향을 주지 않는 것을 의미한다. GET, HEAD, OPTIONS는 단순 조회 이기 때문에 리소스 변경에 영향을 주지 않는다. POST, PUT, PATCH, DELETE 는 변경을 줌으로 안전성에 부합하지 않는 메서드이다.

멱등성

멱등성이란, 여러번의 연산에 상관없이 동일한 결과가 내려오는 것이다. GET, PUT, DELETE, HEAD, OPTIONS 는 당연히 같은 응답이 내려오도록 해야한다. 하지만, POST 와 PATCH는 그렇지 않다.

POST의 경우 같은 요청을 여러번 보내면 여러개의 데이터가 생성(응답)하기 때문에 멱등하지 않고, PATCH의 경우 멱등성을 가지거나 가지지 않게 설계할 수 있다. 예를 들어 요청마다 값을 1씩 증가시키는 경우 멱등성을 가지지 않는다. 하지만, 값을 10으로 업데이트 하는 요청이라면 같은 값으로 업데이트 하기 때문에 멱등성이 인정된다.

캐싱

이런 Method 를 보다보면 캐싱하는 경우가 몇가지 있다. 리소스 변경이 없는 GET의 경우 흔히 캐싱이 일어나지만, 다른 메소드의 경우 캐싱이 어렵다. 리소스 변경이 일어나면 캐싱을 새로 업데이트 해야하는 문제 때문이다. 그렇지만, 이론적으로 POST, PATCH는 캐싱이 가능하지만, 구현이 어렵다는 문제가 있다.

GET 과 POST의 차이점

POST의 경우, GET을 대체할 수 있다는 특징을 가진다. GET에는 리소스를 쿼리 스트링으로 넘겨주게 된다. 하지만, 보안과 관련된 내용이 쿼리 스트링(url) 로 나오게 되면 문제(캐싱 및 기록에 남는것이.. 문제)가 되기 때문에 이런 경우 POST 를 이용하게 된다. POST는 캐싱이나 브라우저(북마크 등)에 기록되지 않기 때문에 GET 보다 문제가 덜하다. 또한, 쿼리스트링에는 길이의 제한이 있기 때문에 많은 데이터를 담기에는 부족해 POST가 나오게 되었다.

PUT 과 PATCH의 차이점 정리

PUT은 전체 수정 PATCH는 일부 또는 전체 수정이고, PUT은 멱등성을 보장해야하지만, PATCH는 상관없다.