REST, RESTful API

REST

• REpresentational State Transfer
  • a way of providing interoperability between computer systems on the Internet. (상호 운용성)

어떻게 인터넷에서 정보를 공유할 것인가? -> 정보들을 하이퍼 텍스트로 연결

• 표현 형식 : HTML
• 식별자 : URI
• 전송방법 : HTTP

"How do I improve HTTp without breaking the Web?, 웹을 망가뜨리지 않고 어떻게 http 기능을 증가시킬 수 있을까?"

RESTful API

• REST API : REST 아키텍처를 따르는 API
• REST : 분산 하이퍼미디어 시스템(ex. 웹)을 위한 아키텍처 스타일
  • 아키텍처 스타일 : 제약 조건의 집합
  • REST에서 정의한 제약 조건을 모두 지켜야 REST를 따른다고 말할 수 있다
• REST 구성 스타일
  1. Client-Server
     2. Stateless
     3. Cache
     4. Uniform Interface
     5. Layered System
     6. Code-on-Demand (optional) : 서버에서 코드를 클라이언트로 보내서 실행할 수 있어야 한다 → 자바스크립트

HTTP만 잘 따라도 Client-Server, Stateless, Cache, Layered System 지킬 수 있음

• Uniform Interface
  • Identification of resources : URI로 리소스가 식별되면 된다
  • Manipulation of resources through representations : representation 전송을 통해서 리소스를 조작 -> 리소스를 만들거나 삭제, 수정할 때 http 메시지에 그 표현을 전송
  • Self-descriptive messages
  • Hypermedia as the engine of application state(HATEOAS)
• Self-Descriptive Messages : 메시지는 스스로를 설명해야 한다.
  • 오늘날의 REST API는 상당히 이를 만족하지 못하고 있다. 대부분 미디어 타입에는 그냥 json이라고만 되어있고 이를 어떻게 해석해야되는지는 명시가 되어있지 않다.
• HATEOAS : 애플리케이션의 상태는 Hyperlink를 이용해 전이되어야 한다.
  

• 자원(resource)의 표현(representation)에 의한 상태 전달
• CRUD (Create, Read, Update, Delete) 연산 수행 -> URI (Resource)로 Method (POST, GET, PUT, PATCH, DELETE) 요청 => 자원 : Representation of Resource로 표현
  
• 자원 (Resource) : URI
  • 고유 ID : HTTP URI
  • 클라이언트 : URI 활용 -> 자원 지정, 해당 자원 상태(정보) 조작을 서버에 요청
• 행위 (Verb) : Method
  • HTTP Protocol (GET, POST, PUT, PATCH, DELETE)
• 표현 (Representation of Resource)
  • 클라이언트 ~ 서버 데이터 송수신 형태
  • JSON, XML, TEXT, RSS

카카오 로컬

• URL 구조, GET Method 사용, JSON, XML Return

주소 검색하기

주소를 지도 위에 정확하게 표시하기 위해 해당 주소의 좌표 정보를 제공하는 API

• 주소에 해당하는 지번 주소, 도로명 주소, 좌표, 우편번호, 빌딩명 등의 다양한 정보를 함께 제공

Request

URL

GET /v2/local/search/address.${FORMAT} HTTP/1.1
Host: dapi.kakao.com
Authorization: KakaoAK ${REST_API_KEY}

Parameter

Response

• meta
  
• document
  
• address
  
• RoadAaddress
  

Sample

• URL

curl -v -X GET "https://dapi.kakao.com/v2/local/search/address.json" \
  -H "Authorization: KakaoAK ${REST_API_KEY}" \
  --data-urlencode "query=전북 삼성동 100" 

• Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "meta": {
    "total_count": 4,
    "pageable_count": 4,
    "is_end": true
  },
  "documents": [
    {
      "address_name": "전북 익산시 부송동 100",
      "y": "35.97664845766847",
      "x": "126.99597295767953",
      "address_type": "REGION_ADDR",
      "address": {
        "address_name": "전북 익산시 부송동 100",
        "region_1depth_name": "전북",
        "region_2depth_name": "익산시",
        "region_3depth_name": "부송동",
        "region_3depth_h_name": "삼성동",
        "h_code": "4514069000",
        "b_code": "4514013400",
        "mountain_yn": "N",
        "main_address_no": "100",
        "sub_address_no": "",
        "x": "126.99597295767953",
        "y": "35.97664845766847"
      },
      "road_address": {
        "address_name": "전북 익산시 망산길 11-17",
        "region_1depth_name": "전북",
        "region_2depth_name": "익산시",
        "region_3depth_name": "부송동",
        "road_name": "망산길",
        "underground_yn": "N",
        "main_building_no": "11",
        "sub_building_no": "17",
        "building_name": "",
        "zone_no": "54547",
        "y": "35.976749396987046",
        "x": "126.99599512792346"
      }
    },
    ...
  ]
}