RESTful HTTP API 구조 및 핵심 개념

기본 배경 지식

• URI:
  - Uniform Resource Identifier
  - 해당 사이트의 특정 자원의 위치를 나타내는 유일한 주소.
  - /login, /news
  - https://finance.naver.com/marketindex/
• HTTP Method
  - HTTP request가 의도하는 action을 정의한것.
  - POST, GET 등등.
• Payload
  - HTTP request에서 보내는 데이터 (body)
  

REpresentational State Transfer

웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고 그 리소스에 대한 행위를 HTTP Method로 정의하는 방식.

• 즉, 리소스(HTTP URI로 정의된)를 어떻게 한다(HTTP Method + Payload)를 구조적으로 깔끔하게 표현하는것.
• Method는 주로 GET과 POST만 사용한다.
• PUT과 DELETE 등도 사용하는 곳도 있지만, 그냥 GET과 POST만 사용하는 것이 단순하기 때문에 GET과 POST만 사용하는 추세.

예를 들어, 삼성전자 주식 정보를 받기 위한 HTTP 요청:

• HTTP GET https://api.trueshort.com/stock/005930

유저의 보유 주식 종목들을 DB에 저장하는 HTTP 요청:

HTTP POST https://api.trueshort.com/user/portfolio

{
    "user_id" : 1,
    "stocks": [ 
        "005930",
        "298730",
        "378900"
    ]
}

RESTful API의 장점

• 여러 장점들이 있지만, 사실 그중 가장 명확한 장점은 바로 self-descriptiveness 이다.
• RESTful API는 그 자체만으로도 API의 목적이 쉽게 이해가 된다.
  - 예를 들어, 위의 HTTP GET https://api.trueshort.com/stock/005930 ` 요청의 경우, 문서나 주석이 없이도 "https://api.trueshort.com 라는 API에서 삼성전자 주식에 관한 정보를 HTTP 요청을 통해 받아오는 구나" 라는 해석이 쉽게 가능하다.
  

RESTful API를 개발할때 유의 할점

/(슬래시)는 계층 관계를 나타낼때 사용된다.

• 예를 들어, https://api.trueshort.com/kospi/stock/005930 이라는 구조라면, KOSPI에 속해있는 주식(Stock) 중 삼성전자(005930)을 나타내는 것이다.
• https://api.shopping.com/books/novel/stephenking 이라는 구조 이라면, 책들중 소설 그리고 소설중 Stephen King의 소설을 나타내는 구조이다.

URI에 _(underscore)는 주로 포함하지않고 또한 영어 대문자보다 소문자를 쓴다. 그리고 너무 긴 단어는 잘 사용하지 않는다. 이 모든건 가독성을 높이기 위해서다.

URI는 명사를 사용한다.

• /books/novel/stephenking 이라고 하지 /books/novel/get-stephenking 이라고 잘 하지 않는다.
• 그 이유는 동사는 GET, POST 같은 HTTP Method를 통해 표현하기 때문이다.