0. RESTFul API 한줄 정리
- REST 아키텍처의 제약 조건(특징)을 준수하는 API
- 일종의 설계 가이드, REST API 설계 가이드에 따라 API를 만들어서 웹 서비스를 제공하면 해당 웹 서비스는 RESTful하다!
1. REST + API
1-1) REST
- REpresentational State Transfer, 어떠한 상태 표현을 주고 받는다
-> 웹상에서 정보들을 주고받을 때 널리 쓰이는 규격화된 통신 규칙
-> "URI"를 통해 웹상에서 사용되는 자원을 표현하고, "HTTP Method"를 통해 자원에 대한 CRUD 요청을 정의하는 방식
1-2) 왜 REST를 사용하고 유명할까?
- REST API의 특징 1: HTTP를 활용한다는 것, 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍쳐 스타일입니다.( HTTP 사용의 모범 사례 )
- REST API 특징 2 : 각 요청이 어떤 동작이나 정보에 의한 것인지 그 모습 자체로 추론이 가능하다는 것
[REST의 구성요소]
1) resource(자원)
- 서버는 유니크한 id를 가지는 리소스를 가지고 있으며, 클라이언트는 리소스에 요청을 보냅니다.
- URI를 통해 표현된다.
ex) 도서관 대출 정보를 관리하는 프로그램을 작성
[id, name, major] --> collections
12, silvia, ~ --> elements/documents
- collections / element가 모여있는 것이 collections, 주로 id값으로 통신을 한다.
2) Verb(행위)
- 위의 리소스를 가공하는 방법은 4가지가 있는데, 이를 CRUD라고 부른다.
그리고 이런 작업들을 REST API에선 Method라고 부르며, 메소드는 HTTP의 method를 사용합니다.
- 자원에 대한 행위는 HTTP Method(GET,PUT,POST,PATCH,DELETE)를 사용해야 한다.
- CRUD 연산 중 각 연산에 맞는 Method를 사용하여 요청을 보낸다.
- CRUD : Create, Read, Update, Delete
Post , Get, (Put, Patch), Delete
ex) 학생 정보를 알고싶다!
GET:: ~주소~/students/12 --id가 12인 학생 정보를 알고싶다
3) Representation of Resource
- 전달하고자 하는 데이터를 표기하는 방법
- 클라이언트가 자원 상태(정보)에 대한 조작을 요청하면 서버는 이에 적절한 응답(representation)을 보낸다.
- 클라이언트와 서버가 데이터를 주고받는 형태로 json, xml, text,rss 등이 있다.
Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.
REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다.
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
[REST API의 설계 가이드]
1) URL에선 명사를 사용한다. (동사 사용 X)
1) 리소스에 대한 행위(method)는 HTTP Method(POST,GET,PUT,DELETE)로 표현해야 한다.
-> get/movies : 모든 영화 리스트를 불러온다
post/movie : 영화를 추가한다.
/컬렉션의 이름을 사용해서 get/movies/incetion : 인셉션 정보를 불러온다.
get/movies/inceptions/
쿼리 파라미터를 사용해서 매번 검색할때마다 URL을 새로 만드는것보다 이게 좋음
2) /(슬래시)는 계층 관계를 나타낼 때 사용하며, 마지막에는 슬래시를 사용하지 않는다.
4) URI에 _(언더스코어)는 사용하지 않으며, 소문자를 사용한다. 긴 단어는 잘 사용하지 않는다.
6) URI에 파일의 확장자를 포함하지 안흔다.
1-4) 왜 REST API일까?
- RESTful API는 그 자체만으로도 API의 목적이 무엇인지 쉽게 알 수 있습니다.
- API를 RESTful 하게 만들어서 API의 목적이 무엇인지 명확하게 하기 위해 RESTful 함을 지향 합니다.
- 이해하기 쉽고 활용도 높은 REST API를 사용하므로써 팀원들도 유용하게 API를 사용할 수 있다.
1-5) RESTFul APi
-RESTful 하지 못한 경우
Ex1) CRUD 기능을 모두 POST로만 처리하는 API
Ex2) route에 resource, id 외의 정보가 들어가는 경우(/students/updateName)
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
[Network] REST란? REST API란? RESTful이란? - Heee's Development Blog
Step by step goes a long way.
gmlwjd9405.github.io
1-5) 단점
- REST는 point-to-point 통신모델을 기본으로 한다. 따라서 서버와 클라이언트가 연결을 맺고 상호작용해야하는 어플리케이션의 개발에는 적당하지 않다.
- REST는 URI, HTTP 이용한 아키텍처링 방법에 대한 내용만을 담고 있다. 보안과 통신규약 정책 같은 것은 전혀다루지 않는다. 따라서 개발자는 통신과 정책에 대한 설계와 구현을 도맡아서 진행해야 한다.
- HTTP에 상당히 의존적이다. REST는 설계 원리이기 때문에 HTTP와는 상관없이 다른 프로토콜에서도 구현할 수 있기는 하지만 자연스러운 개발이 힘들다. 다만 REST를 사용하는 이유가 대부분의 서비스가 웹으로 통합되는 상황이기에 큰 단점이 아니게 되었다.
- CRUD 4가지 메소드만 제공한다. 대부분의 일들을 처리할 수 있지만, 4가지 메소드 만으로 처리하기엔 모호한 표현이 있다.
* 주석
0) API(Application Programming Interface):
응용 프로그램(애플리케이션)에서 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스
주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공합니다.
1) URI : URL은 Uniform Resource Locator로 인터넷 상 자원의 위치를 의미합니다. 자원의 위치라는 것은 결국 어떤 파일의 위치를 의미합니다. 반면에 URI는 Uniform Resource Identifier로 인터넷 상의 자원을 식별하기 위한 문자열의 구성으로, URI는 URL을 포함하게 됩니다. 그러므로 URI가 보다 포괄적인 범위라고 할 수 있습니다.
2) GET/ POST 차이 :
- GET은 웹 브라우저가 서버에 데이터를 요청할 때 사용
- POST는 웹 브라우저가 서버에 데이터를 전달할 때 사용
- GET 사용 시 서버로 전달되는 데이터가 인코딩되어 URL에 붙는다. 따라서 전달되는 데이터가 255개 문자를 초과하면 문제가 발생 할 수 있다.
- POST 방식은 전달되는 데이터가 URL에 표시되지 않는다.
3) PUT/PATCH 차이:
-PUT은 자원의 전체 수정이 필요할 때 사용
-PATCH는 자원의 일부만 수정될 때 사용
RESTFul API 한줄 요약
REST 아키텍쳐의 제약조건을 준수하는 API
REST API 설계 가이드에 따라 API를 만들어서 웹 서비스를 제공하면 해당 웹 서비스는 RESTFul하다고 말합니다.
REST(REpresentational State Transfer)
웹상에서 정보들을 주고받을 때 널리 쓰이는 규격화된 통신 규칙을 의미합니다.
좀 더 자세히 풀어 말하자면, "URI"를 통해 웹상에서 사용되는 자원을 표현하고, "HTTP Method"를 통해 자원에 대한 CRUD 요청을 정의하는 방식입니다. 기존 온라인 데이터 전송 방식인 SOAP 프로토콜의 한계점을 극복하기 위해 등장했다고 합니다.
REST의 특징
- HTTP를 활용합니다. 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍쳐 스타일입니다.(HTTP 사용의 모범 사례)
- 각 요청이 어떤 동작이나 정보에 의한 것인지 그 모습 자체로 추론이 가능합니다.
REST의 구성 요소
1. Resource(자원)
서버는 유니크한 id를 가지는 리소스를 가지고 있으며, 클라이언트는 리소스에 요청을 보낼 수 있습니다. 이 때, 리소스는 URI를 통해 표현된다는 특징이 있습니다. 리소스의 원형으론 document, collection, store, controller가 있는데 document는 DB에서 row처럼 단일 정보를 포함하는 데이터로 생각하면 쉽고 collection은 도큐먼트의 집합을 의미합니다.
IDNAMECLASSMAJOR
| 1 | JONGMIN | AClass | ECONOMICS |
| 2 | JIHYEOK | BClass | C.E |
| 3 | JIHYEON | AClass | MATH |
예를 들어, 도서관 대출 관리 프로그램을 운영한다고 할 때, 위와 같은 학생 정보들이 존재할 것입니다. 이러한 학생 정보를 REST API에선 Resource라고 불립니다. 위 테이블의 전체 정보인 Students를 collection이라고 할 수 있으며, id가 1인 종민 학생의 정보를 document라고 할 수 있습니다.
2. Verb(행위)
리소스를 가공하는 작업들을 REST API에선 Method라고 부르며, HTTP의 Method인 GET/PUT/POST/PATCH/DELETE를 사용합니다. REST API에선 CRUD의 각 연산에 맞는 Method를 사용하여 요청을 보내는 것이 중요합니다. 각 CRUD 연산에서 사용하는 Method는 다음과 같습니다.
CRUD연산--Method
| Create | -- | Post |
| Read | -- | Get |
| Update | -- | Put/Patch |
| Delete | -- | Delete |
3. Representation of Resource(표현)
클라이언트가 자원 상태(정보)에 대한 조작을 요청하면 서버는 이에 적절한 응답(representation)을 보내는데, 이 때 클라이언트와 서버가 데이터를 주고받는 여러 형태를 의미합니다. 즉, 전달하고자 하는 데이터를 표기하는 방법을 의미하며 json,xml,text 등이 있습니다.
REST API 설계 가이드
REST API는 일종의 설계 규약이기 때문에, 어떻게 API를 설계하는지가 REST API에선 중요합니다. REST API의 설계 가이드를 잘 활용해야 RESTFul한 API를 제작할 수 있으며, 이해하기 쉽고 활용도 높은 API를 사용할 수 있을 것입니다.
1. URL에선 명사를 사용한다.
GET: /students/Aclass/15/move (X) GET: /students/Aclass/15 (O)
2. 리소스에 대한 행위(method)는 HTTP Method(POST,GET,PUT,DELETE)로 표현해야 한다.
3. /(슬래시)는 계층 관계를 나타낼 때 사용하며, 마지막에는 항상 엘리먼트(요소, 리소스)가 와야 한다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며, URI의 마지막엔 슬래시로 끝나면 안됩니다.
4. URI에 _ (언더스코어)는 사용하지 않는다.
가독성을 위해 _ 대신 -(하이픈)을 사용하는 것이 좋습니다.
5. 소문자를 사용한다.
대소문자에 따라 다른 리소스로 인식하게 되기 때문입니다. RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정합니다.
6. URI에 파일의 확장자를 포함하지 않는다.
GET / students/Aclass/1/photo.jpg (X) GET / students/Aclass/1/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg
정리
서두에서 언급한 것처럼, RESTFul API는 REST API의 설계 의도를 모두 만족시킨 API입니다. 사실상 REST API의 모든 설계 가이드를 만족시키는 것은 힘들다고 하지만 최대한 RESTFul API에 가까운 API를 설계함으로써 명확하고 구조적인 커뮤니케이션을 이룰 수 있습니다.
참고
1) API(Application Programming Interface)
응용 프로그램(애플리케이션)에서 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스. 주로 파일 제어, 창 제어, 화상 처리, 문자 제어 등을 위한 인터페이스를 제공합니다.
2) URI
URL은 Uniform Resource Locator로 인터넷 상 자원의 위치를 의미합니다. 자원의 위치라는 것은 결국 어떤 파일의 위치를 의미합니다. 반면에 URI는 Uniform Resource Identifier로 인터넷 상의 자원을 식별하기 위한 문자열의 구성으로, URI는 URL을 포함하게 됩니다.
3) GET/ POST 차이
GET은 웹 브라우저가 서버에 데이터를 요청할 때 사용하고, POST는 웹 브라우저가 서버에 데이터를 전달할 때 사용합니다.
GET 사용 시 서버로 전달되는 데이터가 인코딩되어 URL에 붙습니다. 따라서 전달되는 데이터가 255개 문자를 초과하면 문제가 발생 할 수 있습니다.
POST 방식은 전달되는 데이터가 URL에 표시되지 않는다.
4) PUT/PATCH 차이
PUT은 자원의 전체 수정이 필요할 때 사용하고, PATCH는 자원의 일부만 수정될 때 사용합니다.