RESTful API 가 뭔데?

1
2
3
4
5
https://www.googleapis.com/.../calendars/calendar_id
{
    "summary":"일정",
    "timeZone":"Asia/Seoul"
}

REST API는 Representational State Transfer Application Programming Interface 의 약자로,
직역하자면 ‘대표적인 상태 이전을 하는(ful) API’ 정도로 해석할 수 있다.
조금 더 의미있게 의역하자면 ‘어떤 상태에 있는 웹 리소스를 다른 곳으로 옮길 수 있는 소통 방식’이 바로 RESTful API이다.

RESTful API 왜 씀?

웹의 초기에는 HTML에 대한 읽는 행위밖에 제공하지 못했다.

하지만, 웹의 기술이 발전하면서 웹 애플리케이션 이란 형태로 진화하였고,
HTML 을 읽는 행위 이외에도 다른 형태의 데이터(텍스트, 이미지 등등…)를 주고 받는 행위가 가능해졌다.
또한 서버의 리소스를 웹을 통해 제어하기도 했다.

더 많은 데이터를 가지고 더 복잡한 기능들을 구현하려면 서버에선 다른 서버와 데이터를 주고 받거나,
클라이언트에게서 더 많은 데이터를 제공받아야 했다.
그렇지만, 표준화된 규약이 없었기 때문에 기능 발전에는 제한적이었다.

이를 해결하고자 SOAP(Simple Object Access Protocol) 라는 규약이 생겼지만,
‘복잡하고, 어렵고, 무겁다’ 라는 단점으로 현재는 거의 사용하지 않는 방식이 되었다.

2000년에 ‘Roy Fielding’ 이라는 컴퓨터 과학자가 박사학위 논문에서 제시한 REST는
HTTP Method 를 통해 서버의 자원의 상태를 주고 받을 수 있는 새로운 규약으로 자리매김했다.

서버대 서버, 서버대 클라이언트 간 통신 방식으로 새로운 규약이 생기게 된 계기이다.

RESTful API 어떻게 씀?

RESTful API에선 두 가지 문제에 대해 다루고 있다.

  1. Resource를 어떻게 표시할래?
  2. Resource를 어떻게 제어할래?

1. URI로 리소스를 표시

URI(Uniform Resource Identifiers) 로 리소스를 표현한다.
하지만, 가이드가 없다면 설계하는 사람 마음대로 URI를 지정하게 되므로,
다시 통신하는데 어려움이 생기게 된다.

따라서 REST URI 네이밍에는 몇가지 고려해볼만한 규칙이 존재한다.

  1. 지원 리소스 타입
    • Object : 싱글 엔티티(예시 = myplatform.com/customers/1628)
    • Collections : 객체집합(예시 = myplatform.com/customers/)
    • Association : 두 객체 간 관계를 URI에서 표시(예시 = myplatform.com/teacher/1256/class/121)
      (id:1256 선생은 id:121 클래스에 속해있다.)
    • Controllers : 작업을 수행하는 리소스에 대한 절차적인 개념
  2. 명사 vs 동사(명사 우선, 동사는 Case by Case)
    • 개발자는 객체지향적인 패러다임 덕분에 명사에 더 익숙하다
    • 따라서 특별한 경우가 아닌 이상 명사로 유지하는 것이 익숙하다
    • 하지만 동사를 사용하는 것이 때로는 의미가 있을 경우가 있다.
      • 예를 들어, 호텔과 관련된 도메인에서는 check-in이란 동사가
        시간, 손님의 수 등등 명사를 포함하는 개념일 경우가 있다.
  3. 단수형 vs 복수형(Singleton vs Collection)
    • 가능하다면 복수형으로 사용하는 것이 좋다
    • 하지만, 상황에 따라 단수형으로 쓰는 것도 고려 해야 한다
      예를 들어, 차량/엔진 –> vehicles/engine 등 사용 가능한 설계를 고안해야 한다
  4. CRUD에 대한 표현 방식
    • CRUD 를 URI 에 표현하는 방식은 권장하지 않는다.(쿼리 스트링 포함)
      비권장 포맷
      • myservice.com/rooms?action=checkout
      • myservice.com/rooms/delete
  5. 필터 혹은 정렬 필요 시
    • 쿼리 매개변수를 사용하는 것을 권장한다.

2. HTTP Method를 통한 Resource 제어

REST API는 HTTP Method를 통해 각각 CRUD 를 제어한다.

멱등성(Idempotent)

일부 API는 HTTP method 형식에 따라, 그 자원의 형태가 바뀌지 않아야 되는 성질이 있다.
요청 뒤에도 리소스의 상태가 바뀌지 않는 성질을 멱등성이라고 하며,
Rest 에서는 GET, PUT, DELETE 가 이런 멱등성을 만족한다.

GET

리소스의 현재 상태를 가져옵니다. 멱등성

1
2
3
// id = 198 인 고객의 정보를 조회하는 경우
Method: GET
URI: myplatform.com/customers/198

POST

컬렉션에 대해 작동한다. 컬렉션을 만들거나 업데이트 한다.

1
2
3
// 고객을 생성하는 경우
Method: POST
URI: myplatform.com/customers

PUT

단일 리소스에 대해 작동, 해당 상태를 생성하거나 수정한다. 멱등성

1
2
3
// 198 회원 정보를 수정하는 경우 
Method: PUT
URI: myplatform.com/customers/198

DELETE

지정된 개체를 삭제한다. 멱등성

1
2
3
// 198 회원 정보를 삭제하는 경우
Method: DELETE
URI: myplatform.com/customers/198

PATCH

리소스의 부분적인 수정을 할 때 사용

1
2
3
4
5
6
// 198 회원 정보 중 이름만 바꾸고 싶은 경우 
Method: PATCH
URI: myplatform.com/customers/198
{
    "name":"yomni"
}

결론 : RESTful API 는 설계 방식에 대한 개념이기 때문에 절대적인 규칙이 아니다.

RESTful API로 설계한다는 것은 그 시스템의 사용자를 고려하여
적절한 URI에 리소스를 배치시키고, 적절한 method 에 대한 행위를 보장해야 한다.

가령, PATCH를 PUT과 동일하게 사용하도록 서버에서 설계했다면, 멱등성을 만족하고,
일부 속성에 대해서 수정이 가능하도록 설계 할 수도 있다.

이 부분에 대하여 더 자세한 내용을 알고 싶다면, Restful API Design Guide 를 참고하세요.

생각해보자 - 귀에 걸면 귀걸이, 코에 걸면 코걸이

대부분의 개념들은 문제가 있고, 그것을 해결하는 차원에서 학습하면 대부분 이해할 수 있는 경우가 많았는데,
REST API는 자원에 대한 소통 방식을 간단하게 해결한다는 차원에선 쉽게 이해가 가능했지만,
어떻게 설계하느냐에 따라서 전혀다른 결과를 도출할 수도 있다는 점이 어렵게 다가왔다.

역시 이 부분에선 ‘추상도가 높아질 수록 자유도가 높아진다’라는 차원에서 접근해본다면,
API 설계자 입장에선 상당히 어려운 부분이 될 수도 있겠다 라는 것이 느껴졌다.

REST API로 많은 설계를 해봐야 어떤 API 설계에 대한 문제가 주어졌을 때 잘 해결할 수 있을 것 같았다.

–> 많은 도메인에 대해 REST API 로 짜는 연습을 해보자..!!

참고자료