REST API란? [특징, 규칙]

API(Application Programming Interface, 응용 프로그램 프로그래밍 인터페이스)는 응용 프로그램에서 사용할 수 있도록, 운영 체제나 프로그래밍 언어가 제공하는 기능을 제어할 수 있게 만든 인터페이스를 뜻한다. (위키백과)

REST(Representational State Transfer)는 월드 와이드 웹과 같은 분산 하이퍼미디어 시스템을 위한 소프트웨어 아키텍처의 한 형식이다.

제일 큰 의미로는 웹 사이트의 모든 자원 (이미지, 텍스트, DB 등)에 고유한 id (URI)를 부여해 처리하는 것이다.

자원을 이름(표현)으로 구분해서 상태(정보)를 주고 받는데,

자원에 대해 CRUD(Create, Read, Update, Delete)연산을 수행하기 위해 URI로 요청을 보내고 이때 특정한 형태를 사용한다는 것이다.

REST는 웹의 기술과 HTTP 프로토콜을 그대로 활용하여 네트워크 상에서 통신한다.

그렇다면 REST API는 이러한 REST 기반으로 서비스 API를 구현한 것이라 할 수 있다.

 

REST 구성 요소

• 자원(Resource)

서버가 가지고 있는 Unique한 ID, URI라 할 수 있다.

URI를 이용해 클라이언트는 자원을 지정하고, 해당 자원의 정보에 대한 조작을 서버에 요청한다.

 

• 행위(Method)

자원에 대해 수행할 연산으로 HTTP프로토콜의 메소드를 사용한다. (GET, POST, PUT 등..)

 

• 표현(Representation of Resource)

클라이언트가 자원의 상태에 대해 행위를 요청하면 서버는 응답을 보낸다.

이때 표현되는 방식 (받는 형태)로 JSON, XML, TEXT, RSS 등등이 있다.

그럼 이런 REST기술이 난데없이 왜 사용되게 된 걸까

가장 큰 이유로는 다양한 클라이언트에서의 사용과 어플리케이션을 분리 및 통합하기 위해서이다.

이제 웹말고도 다양한 브라우저, 모바일 디바이스 등에서도 서버와 통신을 해야 하는데 html만 보내면 브라우저가 없는 앱에서는 사용할 수 없다.

이때 데이터만 보냄으로써 형식의 제약을 줄여 편하게 이용하는 것이다.

또한 어플리케이션이 이제는 거대해져서, 한 어플리케이션에 일을 하는 여러 모듈들이 분리될 수 있다.

이때 REST API를 사용하여 다른 모듈, 어플리케이션끼리도 통신을 할 수 있게 해준다.

 

REST 특징

• Uniform Interface (일관된 인터페이스)

URI에 대한 요청을 통일되고, 한정적인 인터페이스로 수행한다.

안드로이드, ios, Jsp 등에 무관하게 HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.

 

• Client-Server Architecture (서버 - 클라이언트 구조)

자원이 있는 쪽이 서버 - 요청하는 쪽이 클라이언트

서버는 api를 제공하고, 로직 처리 및 저장, 클라이언트는 사용자 인증, Context(세션, 로그인 정보)등의 역할을 확실하게 구분한다.

 

• Stateless (무상태)

서버에서 각각의 요청은 별개이므로 이전 요청이 다음 요청에 연관되어서는 안된다.

따라서 Rest API는 세션정보, 쿠키정보를 활용하여 상태정보를 저장 및 관리하지 않는다.

서버의 처리방식이 일관성을 유지할 수 있고, 부담이 줄어든다.

 

• Cacheable(캐시 가능)

HTTP 프로토콜을 그대로 사용하므로, 캐시 역시 사용할 수 있다. (Last-Modified Tag, E-Tag로 구현)

 

• Layered System(계층 구조)

Rest API 서버는 여러 계층으로 구성될 수 있다. 여기에 보안, 암호화 등의 계층을 추가하여 구조를 변경할 수 있다.

이때 클라이언트는 Rest API 서버만 호출하고 직접 통신하는지, 중간 서버와 통신하는지는 알 수 없다.

 

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

REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다.

 

REST API 중심 규칙

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

자원은 동사보다는 명사를 사용.

이때 컬렉션은 복수명사, 도큐먼트는 단수명사를 사용해야 한다.

컬렉션 : 도큐먼트들 집합

도큐먼트 : 문서, 객체

http://restapi.example.com/animals/bird/13 -> 여기서 도큐먼트는 bird, 13 / 컬렉션은 animals

 

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

Method	역할
POST	POST를 통해 해당 URI 요청 시 리소스 생성 (Create)
GET	GET을 통해 해당 리소스 조회 (Read)
PUT	PUT을 통해 해당 리소스 수정 (Update)
DELETE	DELETE를 통해 리소스 삭제 (Delete)

이때 URI에 HTTP Method가 들어가선 안된다, 또한 행위에 대한 동사 표현 역시 들어가서는 안된다.

GET /members/delete/1 -> X
GET /members/show/1 -> x

 

설계 유의사항

1) 슬래시 구분자는(/) 계층관계를 사용할 때만 사용하고, 마지막 문자로 포함하지 않는다.

모든 글자는 리소스의 유일한 식별자 -> URI가 다르면 리소스가 다르다.

혼란을 주지 않도록 마지막에 / 넣지 말기

http://restapi.example.com/animals/mammals/ - > X
http://restapi.example.com/animals/mammals - > O

 

2) 가독성을 위해 하이픈(-)을 사용하고, 밑줄(_)은 지양하기

URI를 쉽게 읽기 위해 하이픈을 사용할 수 있다. 이때 밑줄은 잘 보이지 않으므로 하이픈으로 대체하자

 

3) URI 경로에는 소문자를 사용하기

RFC 3986(표준 URI 문법 형식)에서 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정되어있다

대소문자에 따라 다른 리소스가 되어버리기 때문에 최대한 대문자 사용을 피해야 한다

 

4) 파일 확장자는 URI에 포함하지 말기

메시지의 바디 내용 (내용물)의 포맷을 나타내기 위한 파일 확장자를 포함시키지 않는다 (.jpg 이런거 x)

대신 Accept header를 사용하여 표현한다.

http://restapi.example.com/animals/bird/11/photo.jpg
GET / animals/bird/11/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

 

전문가가 아니라 정확하지 않은 지식이 담겨있을 수 있습니다.
언제든지 댓글로 의견을 남겨주세요!

(참고자료) 더 자세하고 깊은 내용들은 아래 링크들에 잘 나와있다! 

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

jeong-pro.tistory.com/180

meetup.toast.com/posts/92