스미스요원

1. REST(Representational State Transfer) API 란 무엇인가?

REST API의 개념과 등장 배경

• 자원을 이름으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미

• 2000년도 로이 필딩(Roy Fielding)의 박사학위 논문에서 최초로 소개된 개념.

    -  HTTP의 주요 저자 중 한 사람

    -  웹(HTTP)이 우수한 설계에 비해 제대로 사용되지 못하고 있음에 안타까워하며 웹의 장점을 최대한 살릴 수 있는
       아키텍처로 REST를 발표했다.

REST API의 구성요소

• 자원(Resource) : URI로 표현된다.

    -  해당 소프트웨어가 관리하는 모든 데이터(문서, 그림 등)

    -  자원의 표현(Representations) : 그 자원을 표시하는 이름

        ◦  예) DB의 학생 정보가 자원일 때, students를 자원의 표현으로 정한다.

    -  URL과 URI의 차이
       

        ◦  https://agentsmith.tistory.com

        ◦  Tistory 블로그 중에서도 agentsmith의 블로그에 대한 경로를 나타내고 있다.

        ◦  서버에서는 해당 라우팅에 대한 알맞은 자원을 전송해줄 것이며, 자원의 실제 위치이므로 URL이다.

        ◦  https://agentsmith.tistory.com/12

        ◦  agentsmith의 티스토리 블로그에서 12의 ID값을 가지는 자원(포스팅)을 식별하고 있다.

        ◦  https://agentsmith.tistory.com 까지는 자원의 실제 위치이기 때문에 URI임과 동시에 URL이며, /12 부분은 식별자이다.

        ◦  즉 위 링크는 URL(https://agentsmith.tistory.com)을 포함한 URI(https://agentsmith.tistory.com/12)라고 할 수 있다. 

• 행위(Verb) : HTTP METHOD(GET, POST, PUT, DELETE)

    -  데이터가 요청되어지는 시점에서 자원의 상태(정보)를 이용한 행위

    -  JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.

핵심정리

• 첫번째  URI는 정보의 자원을 표현해야 한다.

• 두번째  자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

2. 지키면 좋은 간단한 규칙들

URI Rules

• URI는 정보의 자원을 표현해야 한다.

• 자원 이름은 동사보다는 명사를 사용할 것

• 컨트롤 자원을 의미하는 URI는 예외적으로 동사를 허용한다.

• http://agentsmith.tistory.com/12/duplicate

• URI description 규칙

    -  URI 마지막에  /  를 포함시키지 말 것

    -   _  (underbar) 대신  -  (dash)를 사용할 것

    -  소문자를 사용할 것

    -  행위(method)는 URL에 포함하지 말 것

    -  자원에 대한 행위는 URI가 아닌, HTTP Method로 표현할 것

• HTTP Method

    -  GET(조회), POST(생성), PUT(수정), DELETE(삭제) 등

        ◦  GET /members/delete/1 (X)

        ◦  DELETE /members/1      (O)
       -------------------------------

        ◦  GET /members/show/1  (X)

        ◦  GET /members/1           (O)

• Colllection과 Document을 활용하면 좀 더 직관적인 REST API를 설계할 수 있다.

    -  더 큰 개념으로 생각하면 쉬움. 자원에 대한 부가적인 설명을 나타내는 역할

    -  컬렉션 : sports / 도큐먼트 : soccer

        ◦  예) http:// restapi.example.com/sports/soccer

        ◦  예) http:// restapi.example.com/sports/soccer/players/13

​

HTTP Method Rules

• 하나의 자원에 대해 POST, GET, PUT, DELETE 4가지 methods는 반드시 제공할 것

• OPTIONS, HEAD, PATCH를 사용하여 완성도 높은 API를 만들자.

• HTTP status를 method의 리턴값으로 제공할 것

• 성공 응답은 2XX 로 응답한다.

• 실패 응답은 4XX 로 응답한다. (보통 잘못된 URL 접근시 볼 수 있는 에러)

• 5XX 에러는 절대 사용자에게 나타내지 마라 (보통 DB 또는 코드의 잘못으로 나타나는 에러)

3. RequestParam vs PathVariable vs RequestBody

Path Variable

<https://agentsmith.tistory.com/{id}>
<https://agentsmith.tistory.com/12>

• 개별 자원을 구분하여 요청할 때 많이 사용하는 방법

Request Param

<https://agentsmith.tistory.com/?filter=lowPrice>
<https://agentsmith.tistory.com/?startDate=2022-04-20&endDate=2022-04-25>
<https://agentsmith.tistory.com/?page=3>

• 주로 필터링 또는 페이징을 이용해 자원을 요청할 때 많이 사용하는 방법

    -  필터링  낮은 가격 순으로 보기 / 2022-04-20~2022-04-25 만 보기

    -  페이징  데이터가 너무 많아 한 페이지에 한번에 표시하기 어려운 경우

Request Body

{
   "id": 1,
   "name": "홍길동",
   "team": { "id": 1 },
   "email": "gildong@naver.com",
   "position": "intern",
   "createdAt": "2022-04-22",
   "updatedAt": "2022-04-22"
}

• 새로운 자원을 생성하거나(POST), 자원의 정보를 한번에 수정하고 싶을 때(PUT) 주로 사용하는 방법

• JSON 형식의 데이터를 RequestBody에 담아 보낸다.

4. REST API 설계 방식 엿보기

네이버 오픈 API

카카오 오픈 API

구글 오픈 API

5. 참고자료