RESTful API

When Should You Use Path Variable and Query Parameter?

웹에서 특정 데이터를 전송하고 받기 위해서는 어디(End-point)에 요청할 것인가는 중요한 문제!

REST (REpresentational State Transfer) : 웹에 존재하는 모든 자원(resorce)에 고유한 URI를 부여하여 자원에 대한 주소를 지정하는 방법론, 또는 규칙. 현재 가장 널리 사용되고 있음

✓ 기본 배경 지식

• URI (Uniform Resource Identifier)
  • 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소
• HTTP Method
  • HTTP request가 의도하는 action을 정의한 것
• Payload
  - HTTP request에서 server로 보내는 데이터 (body)
  
  

✓ Query parameters (GET parameters)

웹 페이지의 url 주소를 자세히 보면 종종 ?가 포함되어 있음. 이 물음표는 단순한 문자열이 아니라 특정한 기능을 수행. 물음표 뒤에는 늘 key=value 형식의 문자열이 따라오는데 이것을 Query parameter라고 함

주로 데이터를 조건으로 거르거나(filtering), 특정 방식으로 정렬하거나(sorting), 검색(searching)하고자 하는 경우에 활용

/users?id=123 # Fetch a user who has id of 123

• ? 뒤에 id란 변수에 값을 담아 전달하는 방식이 Query string
  • users에 담긴 정보 중 id 123번의 자료를 달라는 요청
    
    

✓ Path parameters

/users/123 # Fetch a user who has id 123

• 동일한 요청을 경로를 지정하여 요청할 수도 있는데 이러한 방식이 Path Variable
  
  

✓ Query string과 Path variable은 각각 언제 쓰면 좋은가?

일반적으로 우리가 어떤 자원(데이터)의 위치를 특정해서 보여줘야 할 경우 Path variable를 적용하고, 정렬하거나 필터해서 보여줘야 할 경우에 Query parameter를 적용

/users # Fetch a list of users
/users?occupation=programer # Fetch a list of programer user
/users/123 # Fetch a user who has id 123

• 위의 방식으로 어디에 어떤 데이터(명사)를 요청하는 것인지 명확하게 정의 가능
• 하지만 그 데이터를 가지고 뭘 하는 것인지 동사는 빠져있는데, 동사 역할을 하는 것이 GET, POST, PUT, DELETE 메소드
• 즉, Query string과 Path variable이 이들 메소드와 결합함으로써 "특정 데이터"에 대한 CRUD 프로세스를 추가의 엔드포인트 없이 완결 지울 수 있게 됨
  • 예시 ) users/create 혹은 users?action=create를 굳이 명시해 줄 필요가 없음

/users [GET] # Fetch a list of users
/users [POST] # Create new user
/users/123 [PUT] # Update user
/users/123 [DELETE] # remove user

Tip! 추가 내용

RESTful이란?

• RESTful은 일반적으로 REST라는 아키텍처를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어
  • ‘REST API’를 제공하는 웹 서비스를 ‘RESTful’하다고 할 수 있음
• RESTful은 REST를 REST답게 쓰기 위한 방법으로, 누군가가 공식적으로 발표한 것이 아님
  • 즉, REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.

RESTful의 목적

• 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것
• RESTful한 API를 구현하는 근본적인 목적이 성능 향상에 있는 것이 아니라 일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것이 주 동기이니, 성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없음

REST의 구체적인 개념

• HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미

REST의 정의

• “Representational State Transfer” 의 약자
• 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미

• 즉, 자원(resource)의 표현(representation) 에 의한 상태 전달
  • a. 자원(resource)의 표현(representation)
    • 자원: 해당 소프트웨어가 관리하는 모든 것 (Ex. 문서, 그림, 데이터, 해당 소프트웨어 자체 등)
    • 자원의 표현: 그 자원을 표현하기 위한 이름 (Ex. DB의 학생 정보가 자원일 때, ‘students’를 자원의 표현으로 정함)
  • b. 상태(정보) 전달
    • 데이터가 요청되어지는 시점에서 자원의 상태(정보)를 전달
    • JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적

• 월드 와이드 웹(www)과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식
  • REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일
  • REST는 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나

REST 구성 요소

• 자원(Resource): URI
  • 모든 자원에 고유한 ID가 존재하고 이 자원은 Server에 존재
  • 자원을 구별하는 ID는 ‘/groups/:group_id’와 같은 HTTP URI
  • Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청
• 행위(Verb): HTTP Method
  • HTTP 프로토콜의 Method를 사용
  • HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공
• 표현(Representation of Resource)
  • Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보냄
  • REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있음
  • JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적