[Network/HTTP] Rest API, Restful API, HTTP Method

REST API

REST를 기반으로 만들어진 API

 

REST

REST는 Representational State Transfer 의 약자로 소프트웨어 프로그램 아키텍처의 한 형식이다.

자원을 이름으로 구분하여 해당 자원의 상태를 주고받는 모든 것을 의미한다. 

월드 와이드 웹(WWW)와 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처의 한 형식이다.

REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다. 

RESTful API를 만들어야 하는 이유

Client Side를 정형화된 플랫폼이 아닌 모바일, pc, application 등 플랫폼에 제약을 두지 않는 것을 목표로 했기 때문이다. 

• 과거에는 pc웹페이지, 모바일 앱 등등에 데해 각각 다르게 서버를 구성하였었는데, 다양한 스마트 기기(TV, 스마트폰, 태블릿...)등 클라이언트 프로그램이 다양화되고 그에 맞춰서 서버를 다르게 구성한다는 것은 매우 비효율적이고 비생산적인 일이 되어버렸다. 
• 따라서 개발자들이 클라이언트 side를 전혀 고려하지 않고 "클라이언트에서 바로 객체로 치환 가능한 형태의 데이터 통신"을 지향하게 되면서 Server와 Client의 역할을 분리하게 되었다. 
• 이렇게 분리하기 위해 필요한 것이 HTTP 표준 규약을 지키면서 API를 만드는 것이다. 

 

RESTful한 API를 작성하기 위해서?

• HTTP URI를 통해 자원을 명시한다.
• HTTP Method(POST, GET, PUT, DELETE, PATCH..)를 통해 해당 자원에 대한 행위를 나타낸다. 

예를 들어 게시판 API를 설계한다고 할 때, 

잘못된 API 설계

글 목록 조회: /read-post-list
id별 글 상세 조회: /read-post-by-id
글 작성: /save-post
글 수정: /update-post
글 삭제: /delete-post

와 같이 "post"라는 자원에 대한 "행위"가 URI에 명시되어 있는경우, RESTful한 API라고 볼 수 없다. 왜냐하면 자원만 HTTP URI에 명시되어있어야 하는데, "자원에 대한 행위"가 같이 명시되어 있기 때문이다. 

올바른 API 설계

글 목록 조회: /posts
id별 글 상세 조회: /posts/{id}
글 작성: /posts/{id}
글 수정: /posts/{id}
글 삭제: /posts/{id}

계층 구조 상 상위를 컬렉션으로 보기 때문에 복수 단어를 사용하기를 권장한다고 한다. 따라서 post가 아니라 posts로 명시해주어야 한다. 

위와 같이 API 설계를 하는 것이 바른 설계이다. 행위가 처음의 API 설계와 다르게 URI에 나타나지 않고 리소스만 나타나고 있다. 그렇다면 리소스에 대해 "어떤 행위"를 하고싶은지는 어떻게 알 수 있을까?

->  HTTP Method를 통해 알 수 있다. 

 

HTTP Method

GET: 리소스 조회

• 서버에 전달하고 싶은 데이터는 "쿼리"를 통해서 전달한다. 
• "바디"를 사용해서 전달도 가능하지만, 지원하지 않는 클라이언트가 많기 때문에 권장되지 않는다. (나도 RestAPI를 모르고 API설계를 했을 때 바디에 GET 메서드를 사용해야 할 때 "메시지 바디"에 데이터를 넣어서 보내도록 코드를 짰었는데 안드로이드 레트로핏에서는 get 메서드에서 바디를 보낼 수 없다고해서 코드를 수정했던 경험이 있다.)

POST: 요청 데이터 처리

• "메시지 바디"를 통해 서버로 요청 데이터를 전달한다.
• 서버는 요청 데이터를 "처리"한다. 
• 주로 신규 리소스를 데이터베이스에 저장하고, 프로세스를 처리하는 경우에 사용한다. (회원가입, 게시판 글 작성, 댓글 작성..)
• 프로세스를 처리하는 경우에는 새로운 리소스가 생성되지 않아도 사용될 수도 있다. 
• JSON으로 조회 데이터를 넘겨야하는 경우에 GET 메서드가 불가하므로 이때 POST 메서드를 사용하기도 한다. 

PUT: 리소스를 대체

• 리소스가 있으면 대체하고 없으면 생성해서 덮어버린다고 생각하면 된다. 
• "클라이언트가 리소스를 식별"하는 경우에 사용한다. 
• 근데 만약에 제목과 내용을 담은 게시글을 수정하는 경우에 이 메서드를 사용할 경우, 클라이언트에서 게시글의 제목만 보낼 경우에 제목만 수정이 되고 내용은 아예 사라져버리기 때문에 이 점에 유의해서 메서드를 사용하여야 한다. 하지만, 나는 제목만 수정하고싶은데 내용까지도 보내야하는 걸까? 이 문제를 해결할 수 있는 메서드가 PATCH 메서드이다.

PATCH: 리소스 부분 변경

• 리소스의 부분만 변경을 해준다.
• 게시글의 제목 부분만 수정하고 싶다고 할 때, 제목만 보내면 제목이 수정이 된다. 

 

References

인프런(김영한) - 모든 개발자를 위한 HTTP 웹 기본 지식(https://www.inflearn.com/course/http-%EC%9B%B9-%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC/dashboard)

 

https://khj93.tistory.com/entry/%EB%84%A4%ED%8A%B8%EC%9B%8C%ED%81%AC-REST-API%EB%9E%80-REST-RESTful%EC%9D%B4%EB%9E%80

[네트워크] REST API란? REST, RESTful이란?

https://velog.io/@somday/RESTful-API-%EC%9D%B4%EB%9E%80

RESTful API 이란