[WEB] Restful API

[API란?]

- Application Programming Interface, 응용 프로그램 사이를 연결하는 인터페이스

- 응용 프로그램간의 상호작용 방식

- 어떤 응용프로그램에 다른 소프트웨어 기능을 제공한다

- 따라서, 개발하는 응용프로그램의 확장을 쉽게 해주고 응용 프래로그램의 기능을 다채롭게 해준다

 

[REST란?]

1. REST의 개념

- REST(REpresentation State Transfer, )

- Roy Fielding의 논문에서 처음으로 소개됨

- HTTP를 기반으로 필요한 자원에 접근하는 방식을 정해놓은, 분산 하이퍼미디어 시스템을 위한 소프트웨어 개발 아키텍처

(*아키텍처 : 애플리케이션을 설계, 제작하는 데 사용하는 패턴과 기술의 총칭)

 

2. REST의 특징 (RESTful 조건)

- Server-Client 구조 : 자원은 서버에 있고, 자원 요청은 클라이언트가 함

- 무상태 : 자원을 필요로 하는 요청자의 정보나 데이터를 굳이 저장하지 않음 (HTTP프로토콜 자체가 무상태이므로,,)

- 캐시 가능 : 같은 URI에 대한 반복된 요청을 효율적으로 처리

- 일관된 인터페이스 : HTTP를 사용하는 환경이라면 플랫폼에 상관없이 사용

- 자체표현구조 : JSON, XML 등 을 이용하는 메시지 구조로 해당 메세지가 어떤 것을 요구하는지 직관적으로 해석 가능

- 계층구조 : REST 서버 구조는 다중계층으로 구성 가능하여 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이같은 네트워크 기반의 중간 매체를 둘 수 있음

*로드밸런싱 : 네트워크 또는 서버에 가해지는 로드를 분산시켜주는 기술 (컴퓨터 자원들에게 작업을 나누는 것을 의미)

*PROXY : 서버와 클라이언트 사이의 중계기로서 대리로 통신을 수행하는 것

*게이트웨이 : 한 네트워크에서 다른 네트워크로 이동하기 위해 거쳐야 하는 지점

- 구성요소 : 자원, 행위, 표현

 

[REST의 구성요소]

1. 자원
- 모든 자원은 고유한 ID를 가짐

- ID는 서버에 존재

- 자원에 접근할 때, URI(자원의 위치를 나타냄)를 사용함

2. 행위
- 클라이언트는 URL을 이용해 자원을 지정하고 자원을 조작하기 위해 Method를 사용

HTTP method	설명
GET	필요한 자원을 조회
HEAD	GET방식과 비슷하나, 정보만 확인
POST	자원을 자신의 응용 프로그램에 추가
PUT	응용프로그램에서 활용하는 자원을 변경
PATCH	존재하는 자원을 부분적으로 변경
DELETE	자원을 더이상 필요로 하지 않을 때 삭제함 (사용자의 적절한 인증 필요)

 

3. 표현(Representation)
- 클라이언트가 서버로 요청을 보냈을 때 응답 자원의 상태를 Representation이라고 함

- REST에서 자원은 JSON, XML, RSS등 여러 형태의 Representaion으로 나타낼 수 있음

 

[REST의 장단점]

1. 장점

- HTTP 기반 사용으로, 별도의 인프라 구축 필요 없음 & HTTP가 사용 가능한 환경이라면 플랫폼에 상관없이 사용 가능

- 외부 문서 없이 메세지가 자체적으로 무엇을 의미하는지 표현하므로 사용이 쉬움

- 캐싱 가능 (다른 api 스타일은 캐싱을 위해 추가적인 모듈이 필요하다)

 

2. 단점

- 명확한 표준이 없음 (REST의 표준을 따르지 않으면서 REST API로 불리기도 함,,) 상황에 따라 달라지므로 실질적으로는 구현하기 어렵다

- HTTP 기반 사용으로 제한된 메서드 기능 (CRUD)

- REST에서는 JSON, XML을 사용하여, RDBMS와는 맞지 않음

 

[REST의 아키텍처 스타일]

1. 설계 제약 조건

- 클라이언트-서버 구조여야 한다

- 일관성 있는 인터페이스 : 장비/애플리케이션 타입과 무관하게 목표 서버와 통신하고록 일관성 있는 통신방법을 허용한다

- 무상태 : 서버와 세션에 대한 내용을 저장하지 않는다

- 캐싱이 가능해야 한다

- 계층화되어있어야 한다

- 서버가 클라이언트에서 실행가능한 코드를 제공할 수 있어야 한다

 

[RESTful API란?]

- REST아키텍처 스타일의 제약조건을 준수하고 RESTful웹 서비스와 상호작용할 수 있는 애플리케이션 프로그래밍 인터페이스

 

[REST API설계 예시]

1. URI 작성시, 소문자를 사용한다

- 대문자는 문제를 일으키는 경우가 있어, camelCase형식보다는 "-"를 사용해 소문자로만 작성한다

- BAD : http://api.example.com/backendStudy

- GOOD : http://api.example.com/backend-study

 

2. URI 작성시 마지막에는 슬래시를 포함하지 않는다

- 전혀 의미가 없기 때문이다 (있든 없든, 같은 것으로 취급!)

- 그러나, URI내의 모든 문자는 리소스의 고유 ID에 포함되므로 아래의 두 URI는 두 개의 다른 리소스에 매핑된다

- URI가 다르면 리소스가 다르며, 리소스가 다르면 URI도 다르다.

- BAD : http://api.example.com/backend-study/

- GOOD : http://api.example.com/backend-study

 

3. 계층관계를 나타낼 때에는 슬래시'/'를 사용한다

- 자원 간의 계층적 관계를 나타낼 때에는 슬래시를 사용하고

- URI내에 행위(메서드)는 작성하지 않는다. 행위는 메서드를 통해서만 전달한다

- BAD : http://api.example.com/backend-study/students/get-sanghee

- GOOD : http://api.example.com/backend-study/students/sanghee

 

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

- Content-type이라는 헤더를 통해 전달되는대로 미디어 타입을 사용하여 body의 콘텐츠를 처리하는 방법을 결정한다

- Rest API클라이언트는 HTTP에서 제공하는 형식 선택 메커니즘인 Accept 요청 헤더를 활용하도록 권장해야 한다

*Accept요청 HTTP 헤더 : 클라이언트가 이해 가능한 컨텐츠 타입이 무엇인지를 알려줌, 컨텐츠 협상을 이용해, 서버는 제안 중 하나를 선택하고 사용하며 Content-Type응답 헤더로 클라이언트에게 선택된 타입을 알림

 

5. 전달하고자 하는 자원의 명사를 사용하되, 컨트롤 자원을 의미하는 경우 예외적으로 동사를 허용한다

- http://api.example.com/backend-study/students/sanghee/edit

 

6. URI에 작성되는 영어를 복수형으로 작성한다
- 실무에서는 표현할 때 URI의 형식을 복수형으로 주로 사용한다

- BAD : http://api.example.com/backend-study/students/sanghee/web

- GOOD : http://api.example.com/backend-study/students/sanghee/webs