REST, REST API, RESTful 이란 ?

REST 란 ?

• REST 정의

REST(Representational State Transfer)

REST는 웹에서 데이터를 전송하고 처리하는 방법을 정의한 인터페이스를 말한다. 모든 데이터 구조와 처리방식은 REST에서 URL을 통해 정의된다. 그렇기 때문에 매우 직관적으로 이해하기 쉽다.

 

 

• REST 개념

HTTP URI(Uniform Resource Identifier)를 통해 자원(Resource)을 명시하고, HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다. 

REST는 자원 기반의 구조(ROA, Resource Oriented Architecture) 설계의 중심에 Resource가 있고 HTTP Method를 통해 Resource를 처리하도록 설계된 아키텍쳐를 의미한다. 웹 사이트의 이미지, 텍스트, DB 내용 등의 모든 자원에 고유한 ID인 HTTP URI를 부여 한다. 즉, 자원을 이름(자원의 표현)으로 구분하여 해당 자원의 상태(정보)를 주고 받는 모든 것을 의미한다. 

• 자원(Resource): 해당 소프트웨어가 관리하는 모든 것
• ex) - 문서, 그림, DB, 이미지, 동영상, 해당 소프트웨어 자체 등
• 자원의 표현(Resource Representation): 해당 자원을 표현하기 위한 이름 
• ex) - DB의 학생 정보가 자원일 때, "students"를 자원의 표현으로 정한다. 
• 자원의 상태: 데이터
• ex) - 자원의 상태를 주고 받는 다는 것은 결룩 데이터를 주고 받는다는 의미

 

 

• CRUD Operation - HTTP Method

• Create: 생성(POST)
• Read: 조회(GET)
• Update: 수정(PUT | PATCH) - (전체 내용을 수정=PUT, 부분 내용을 수정=PATCH)
• Delete: 삭제(DELETE)

 

 

• 상태(정보) 전달

데이터가 요청되어지는 시점에서 자원은 상태(정보)를 전달한다. - HTTP Status Code

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

 

 

REST는 기본적으로 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일이다. REST는 네트워크 상에서 Client와 Server 사이의 통신 방식 중 하나이다. 

 

 

REST의 장단점

장점

1. 쉬운 사용

- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API 사용을 위한 별도의 인프라를 구축할 필요가 없다.

 

2. Client - Server 역할의 명확한 분리

- Client는 REST API를 통해 서버와 정보를 주고 받는다. REST의 특징인 Stateless에 따라 서버는 클라이언트의 Context를 유지할 필요가 없다.

 

3. 특정 데이터 표현을 사용 가능

- REST API는 헤더 부분에 URI 처리 메소드를 명시하고 필요한 실제 데이터를 "body"에 표현할 수 있도록 분리 시켰다. JSON, XML 등 원하는 Representation(표현) 언어로 사용 가능하다. 

 

4. 범용성

- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.

- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다.

 

5. 그외

- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해준다.

- REST API 메시지가 의도하는 바를 명확하게 나타내므로 으도하는 바를 쉽게 파악할 수 있다.

- 여러 가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다.

 

단점

- 표준이 자체가 존재하지 않아 정의가 필요하다.

- 사용할 수 있는 메소드가 4가지밖에 없다.

- 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 정보의 값을 처리해야 하므로 전문성이 요구된다.

- 구형 브라우저에서 호환이 되지 않아 지원해주지 못하는 동작이 많다.

 

 

REST의 특징

• Uniform (유니폼 인터페이스)

- HTTP 표준에만 따른다면, 안드로이드/IOS 플랫폼이든, 특정 언어나 기술에 종속되지 않고 모든 플랫폼에 사용할 수 있 으며, URI로 지정한 리소스에 대한 조작이 가능한 아키텍처 스타일을 의미한다. 

 

• Stateless (무상태성)

- REST는 무상태성 성격을 가진다. 다시 말해 작업을 위한 상태정보를 따로 저장하고 관리하지 않는다. 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 된다. 그래서 서비스의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다.

 

• Cacheable (캐시 가능)

- REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있다. 따라서 HTTP가 가진 캐싱 기능이 적용할 수 있다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다. 

 

• Self-descriptiveness (자체 표현 구조)

- REST의 또 다른 큰 특징 중 하나는 REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조로 되어 있다는 것이다. 

 

• Client - Server 구조

- REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간 의존성이 줄어 들게 된다.

 

• 계층형 구조

- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다. 

 

 

REST 구성 요소

1. 자원(Resource): URI

- 모든 자원에 고유한 ID가 존재하고, 이자원은 Server에 존재한다.

- 자원을 구별하는 ID는 "Students/1" 와 같은 HTTP URI 이다.

- Client는 URI를 이용해서 자원을 지정하고 각 자원의 상태를 조작하기 위해 Server요청을 보낸다. 

 

2. 행위(Verb): HTTP Method

- HTTP 프로토콜의 Method를 사용한다.

- HTTP 프로토콜은 GET, POST, PUT, DELETE와 같은 Method를 제공한다.

 

3. 표현(Representation)

- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다.

- REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.

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

 

 

 

HTTP와 REST

HTTP(HyperText Transfer Protocol)는 웹 환경에서 정보를 주고 받기 위한 프로토콜 이다.

- 클라이언트는 HTTP의 상태 코드를 확인하여 요청의 성공 | 실패 를 확인할 수 있다.

- 이것은 HTTP를 사용하는 클라이언트와 서버 간의 약속, 프로토콜인 것이다. 



REST(Representational State Transfer)는 분산 하이퍼 미디어 시스템을 위한 소프트 웨어 아키텍처 이다. 


즉, HTTP는 웹 환경에서 정보를 송수신할 때 사용하는 약속이고, REST는 소프트웨어 아키텍처 이다. 

REST에서 반드시 HTTP가 필요한 것은 아니다. WAP, WebRTC, MQTT등 다른 프로토콜로도 이용 가능 하다.

REST는 소프트웨어 아키텍처(설계 지침, 원리 등등)고 REST에서 Client - Server간 통신 시 HTTP를 사용한 것이다.


REST에서 HTTP는?

REST에서 HTTP는 필수가 아니지만, 웹 환경 통신의 대부분이 HTTP를 사용한다. 만약, 어떤 API의 요청 | 응답 데이터 포맷이 YAML이면 어떨까? 물론 YAML이 JSON 포맷의 데이터를 대체하여 표현할 수 있고 JSON이 갖는 한계를 보완한 부분도 있지만, 일반적이지 않다. 일반적이지 않은 것은 불편함을 야기한다. 이러한 불편함을 감수하면서 일반적이지 않는 것을 사용하려면 매우 설득력 있는 근거가 필요하고 REST의 경우엔 현재로선 없다. 

REST는 HTTP를 사용하는 것이 일반적이다. 필수가 아니라고 했지만, 거의 필수다. REST의 개념/원리에는 HTTP가 필수는 아니지만, 그 사용에 있어 필수적으로 변한 경우이다.  

따라서 REST를 이용해 API를 설계하려면 HTTP에 대해서 알고 있어야 한다.

 

 

 

REST API 란?

• API(Application Programming Interface) 란?

- 데이터와 기능의 집합을 제공하여 컴퓨터 프로그램간 상호작용을 촉진하며, 서로 정보 교환을 가능 하도록 하는 것 

- 사람을 위한 인터페이스가 아니라 프로그램을 위한 인터페이스 이다. 즉, 프로그램 간 커뮤니케이션을 담당하는 기능 

 

 

• REST API의 정의

- REST 기반으로 서비스 API를 구현한 것 

- 웹상에서 사용되는 여러 리소스를 HTTP URI로 표현하고, 해당 리소스에 대한 행위를 HTTP Method로 정의하는 방식을 말한다.

 

 

• REST API의 특징

- 사내 시스템들도 REST 기반으로 시스템을 분산해 확장성과 재사용성을 높여 유지 보수 및 운용을 편리하게 할 수 있다.

- REST는 HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 Client, Server를 구현할 수 있다.

- REST API를 제작하면 델파이 Client 뿐 아니라, Java, C#, Web 등을 이용해 Client를 제작할 수 있다.

 

 

• REST API 디자인 가이드

REST API 설계 시 가장 중요한 항목은 다음의 2가지로 요약할 수 있다.

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

- Resource(자원)는 동사보다는 명사를, 대문자 보다는 소문자를 사용한다.

- Resource(자원)의 도큐먼트 이름으로는 단수 명사를 사용해야 한다.

- Resource(자원)의 컬렉션 이름으로는 복수 명사를 사용해야 한다.

- Resource(자원)의 스토어 이름으로는 복수명사를 사용해야 한다.

 

* 도큐먼트: 객체 인스턴스나 데이터베이스 레코드와 유사한 개념

* 컬렉션: 서버에서 관리하는 디렉터리 리소스

* 스토어: 클라이언트에서 관리하는 리소스 저장소

 

 

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

- URI에 HTTP Method가 들어가면 안된다. (리소스명은 동사보다는 명사를 사용)

ex) - GET  /members/delete/1  =>  DELETE  /members/1

- GET  /members/delete/1 같은 방식은 REST를 제대로 적용하지 않은 URI이다. URI는 자원을 표현하는데 중점을 두어야한다. 따라서 delete같은 해우이에 대한 표현이 들어가서는 안된다.

- DELETE  /members/1 즉, 이같은 방식으로 수정해야한다. (자원에 대한 행위는 HTTP Method로 표현)

  회원정보를 가져올 때는 GET, 회원 추가 시의 행위를 표현하고자 할때는 POST Method를 사용하여 표현

- URI에 행위에 대한 동사 표현이 들어가면 안된다.

  (CRUD 기능을 나타내는 것은 URI에 사용하지 않는다.)

ex) - GET  /members/show/1  =>  GET  /members/1

ex) - GET  /members/insert/2  =>  POST  /members/2

- 경로 부분 중 변하는 부분은 유일한 값으로 대체한다.

  (:id는 하나의 특정 Resource를 나타내는 고유값이다.)

ex) - student를 생성하는 route: POST/students

ex) - id=12 인 student를 삭제하는 route: DELETE /students/12

 

• HTTP Method의 알맞은 역할

POST, GET, PUT, DELETE 이 4가지의 Method를 가지고 CRUD를 한다.

Method	역할
POST	POST를 통해 해당 URI를 요청하면 리소스를 생성합니다.
GET	GET를 통해 해당 리소스를 조회합니다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다.
PUT	PUT를 통해 해당 리소스를 수정합니다.
DELETE	DELETE를 통해 리소스를 삭제합니다.

다음과 같은 식으로 URI는 자원을 표현하는 데에 집중하고 행위에 대한 정의는 HTTP Method를 통해 하는 것이 REST한 API를 설계하는 중심 규칙이다.

 

• REST API URI 설계 시 주의할 점(규칙)

1. 슬래시 구분자(/)는 계층 관계를 나타내는데 사용

http://restapi.example.com/houses/apartments
http://restapi.example.com/animals/mammals/whales

 

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다. REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.

http://restapi.example.com/houses/apartments/ (X)
http://restapi.example.com/houses/apartments  (0)

 

3. 하이픈(-)은 URI 가독성을 높이는데 사용

URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈(-)을 사용해 가독성을 높일 수 있다.

 

4. 밑줄(_)은 URI에 사용하지 않는다

글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 대문에 문자가 가려지기도 한다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋다. (가독성)

 

5. URI 경로에는 소문자가 적합하다

URI 경로에 대문자 사용은 피하도록 한다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문이다. RFC3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이다.

    RFC 3986 is the URI (Unified Resource Identifier) Syntax document

 

6. 파일 확장자는 URI에 포함시키지 않는다.

    http://restapi.example.com/members/soccer/345/photo.jpg (X)

REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI안에 포함시키지 않는다.

Accept header를 사용하도록 한다.

    GET / members/soccer/345/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

 

• 리소스 간의 관계를 표현하는 방법

REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현 방법으로 사용한다.

    /리소스명/리소스 ID/관계가 있는 다른 리소스명

    ex)    GET : /users/{userid}/devices (일반적으로 소유 ‘has’의 관계를 표현할 때)

만약 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다. 예를 들어 사용자가 '좋아하는' 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용 될 수 있다.

    GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)

 

• REST API 설계 예시

CRUD	HTTP verbs	Route
Resource들의 목록을 표시	GET	/resource
Resource 하나의 내용을 표시	GET	/resource/:id
Resource를 생성	POST	/resource
Resource를 수정	PUT	/resource/:id
Resource를 삭제	DELETE	/resource/:id

 

 

• HTTP 응답 상태 코드

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다. 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수가 있기 때문에 응답의 상태코드 값을 명확히 돌려주는 것은 생각보다 중요한 일이 될 수도 있다. 

상태코드에 대해서는 몇 가지만 정리

상태코드
200	클라이언트의 요청을 정상적으로 수행함
201	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업시)
301	클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드 (응답 시 Location header에 변경된 URI를 적어 줘야 합니다.)
400	클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
401	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드 (로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)
403	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드 (403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에)
405	클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드
500	서버에 문제가 있을 경우 사용하는 응답 코드

추가

• 1xx: 전송 프로토콜 수준의 정보 교환
• 2xx: 클라이언트 요청이 성공적으로 수행됨
• 3xx: 클라이언트는 요청을 완료하기 위해 추가적인 행동을 취해야 함
• 4xx: 클라이언트의 잘못된 요청
• 5xx: 서버쪽 오류로 인한 상태 코드 

 

 

RESTful 이란?

- RESTful은 일반적으로 REST 라는 아키텍처를 구현하는 웹 서비스를 나타내기 위해 사용되는 용어이다.

• "REST API"를 제공하는 웹 서비스를 "RESTful"하다고 할 수 있다.

- RESTful은 REST를 REST답게 쓰기 위한 방법으로, 누군가가 공식적으로 발표한 것이 아니다.

• 즉, REST 원리를 따르는 시스템은 RESTful이란 용어로 지칭된다.

 

RESTful의 목적

- 이해하기 쉽고 사용하기 쉬운 REST API를 만드는 것

- RESTful한 API를 구현하는 근복적인 목적이 성능 향상에 있는 것이 아니라 일관적인 컨벤션을 통한 API의 이해도 및 호환성을 높이는 것이 주 동기이며 성능이 중요한 상황에서는 굳이 RESTful한 API를 구현할 필요는 없다.

 

 

RESTful 하지 못한 경우

- CRUD 기능을 모두 POST로만 처리하는 API

- route에 Resource, id 외의 정보가 들어가는 경우(/students/updateName)

 

 

 

참고

meetup.toast.com/posts/92

REST API 제대로 알고 사용하기 : NHN Cloud Meetup

gmlwjd9405.github.io/2018/09/21/rest-and-restful.html

[Network] REST란? REST API란? RESTful이란? - Heee's Development Blog

www.slipp.net/wiki/pages/viewpage.action?pageId=12878219

8주차 - REST API 설계 및 구현 - SLiPP 스터디 - SLiPP::위키