[Section2] Rest API

1. REST API

    a. API란?

    - 내가 이해했던 API는 기능 구현을 위한 복잡한 코드를 이면에 숨겨두고 외부적으로는 간단한 코드 하나로 원하는 기능을 구현하게끔 해주는 것이다.
    - 다음은 AWS 문서에 정의된 API다.

    "API는 소프트웨어 간에 커뮤니케이션이 가능하도록 만드는 매커니즘이다"(정의와 프로토콜의 집합을 사용해서) 휴대폰의 날씨 앱은 API를 통해 기상청의 시스템과 통신하여 기상청 소프트웨어에 존재하는 일일 날씨 데이터를 보여줄 수 있다.
    "Application은 고유한 기능을 가진 모든 소프트웨어이며 interface 는 두 어플리케이션 간의 서비스 계약이다" 이 계약은 요청과 응답을 사용하여 두 어플리케이션이 서로 통신하는 방법을 정의한다.

    - REST API는 이 API를 작동시키는 방법 중 하나다.

    b. Representational State Transfer

    - REST는 웹의 장점을 활용할 수 있는 아키텍처다.  REST API는 이런 REST 아키텍처 스타일을 따르는 API이다.
    - 아키텍처 스타일이란? 제약조건의 집합이며, 이 제약조건을 모두 지켰을 때 REST를 따른다고 말할 수 있다.

    c. 웹에서 사용되는 데이터나 자원을 HTTP URI로 표현하고, HTTP 프로토콜을 통해 요청과 응답을 정의하는 방식이다.

2. REST 성숙도 모델

- 0~3단계까지 총 4개 단계로 이루어진다.

    a. 0단계

    - 단순히 HTTP 프로토콜을 사용하기만 하는 단계.
    - 병원 예약을 하는 경우 요청은 단순히 /appointment 라는 URI로 이루어진다.

      i. 예약 가능한 시간 요청 예시

        POST /appointment HTTP/1.1
        {
            "date" : "2002-08-10",
            "doctor" : "허준"
            }

       ii. 응답 예시

        HTTP/1.1 200 OK
        {
            "slots" : [
            { "doctor" : "허준", "start" : "09:00", "end" : "12:00" },
            { "doctor" : "허준", "start" : "14:00", "end" : "16:00" }
                ]
        }

       iii. 특정 시간 예약 요청도 동일하게 POST로 한다.

        POST /appointment HTTP/1.1
        {
            "doctor" : "허준",
            "start" : "14:00",
            "end" : "15:00",
            "patient" : "김코딩"
            }

    b. 1단계

    - 1단계에서는 요청을 할 때 HTTP URI가 리소스를 표현한다. /doctors/허준 이라는 URI로 허준이라는 의사의 예약가능시간을 요청한다. 여기서 /doctors/허준을 엔드포인트라 한다.
    - 이에 대한 응답으로 예약가능한 특정 시간대에 id : 123이 왔다 치면, 이 id를 기반으로 다시 예약 요청을 보낸다. 이 때의 엔드포인트는 /slots/123이 된다.
    - 엔드 포인트는 명사로 한다.

    c. 2단계

    - 2단계는 CRUD에 맞게 적절한 HTTP 메서드를 사용하는 단계다. 1단계 까지는 POST요청으로 모든 요청을 했지만, 단계는 에약 조회는 GET, 예약 요청은 POST메서드로 한다.

       i. GET요청

        - GET요청은 body를 가지지 않기 때문에 URI query로 요청을 전달한다.
        - /doctors/허준/slots?date=2022-08-10 이렇게 query로 요청한다.

       ii. POST 요청에 대한 응답

        - 200OK가 아닌 201 Created와 같은 명확한 응답을 해야하고, Location 헤더에 작성된 URI를 통해 클라이언트가 리소스를 확인할 수 있어야 한다.

       iii. 메서드 구분 사용

        - GET은 서버의 데이터를 변화시키지 않는 요청에 사용하고, POST는 요청마다 새로운 리소스를 생성하고, PUT은 요청마다 같은 리소스를 반환해야할 때 사용한다. 
        - PUT은 정보를 통째로 교체할 때, PATCH는 일부분을 수정할 용도로 사용한다.

    d. 3단계

        i. HATEOAS(Hypermedia As The Engine Of Application State)
        - 요청은 2단계와 동일하지만 응답에는 리소스의 URI를 포함한 링크요소를 삽입해야한다. 예를 들면, 예약 확인 요청에 대한 응답에 예약 링크를 담아서 응답하는 식이다.

3. 추가 자료

    a. 왜 REST API가 만들어졌는가?

    - How do I improve HTTP without breaking the Web이라는 물음에서 시작되었다. REST API의 제약 조건을 모두 지키면(이 중에서 Uniform interface) 서버와 클라이언트가 각각 독립적으로 진화가 가능하다.  
    - 독립적으로 진화를 한다면 서버의 기능이 변경되어도 클라이언트를 업데이트할 필요가 없다.

    b. HATEOAS

    - 게시판에 글쓰기 요청(GET /new-form) -> 글 저장(POST /articles) -> 작성된 글 보기(GET /articles/10) -> 게시글 목록 요청(GET /articles) 이렇게 링크가 삽입되어 전이가 가능하게끔 한 것.