REST API
API(Application Programming Interface)란
- 데이터와 기능의 집합을 제공하여 컴퓨터 프로그램간 상호작용을 촉진하며 서로 정보를 교환 가능하도록 하는 것이다
REST API란?
- REpresentaional State Transfer 의 약자이다. WWW과 같은 분산 하이퍼 미디어 시스템을 위한 아키텍처 스타일이며 2000년 Roy Fielding이 논문에서 처음 발표 했다.
- 자원을 이름으로 구분하여 해당 자원의 상태를 주고 받는 모든 것을 의미한다
- REST의 구체적인 개념
- HTTP URI(Uniform Resource identifier) 를 통해 자원 (Resources)을 명시하고 HTTP Method(POST, GET, PUT, DELETE)를 통해 해당 자원에 대한 CRUD Operation을 적용하는 것을 의미한다
REST API 특징
- 확장성과 재사용성을 높여 유지보수 및 운용을 편리하게 할 수 있다
- REST는 HTTP 표준을 기반으로 구현하므로, HTTP를 지원하는 프로그램 언어로 클라이언트, 서버를 구현할 수 있다
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 외의 정보가 들어가는 경우(/users/updateName)
REST 구성
- REST API는 아래와 같이 구성되어있다
- 자원(RESOURCE)
- URI
- 행위(Verb)
- HTTP METHOD
- 표현(Representations)
- 자원(RESOURCE)
REST의 장단점
장점
- HTTP 프로토콜의 인프라를 그대로 사용하므로 REST API사용을 위한 별도의 인프라를 구출할 필요가 없다.
- HTTP 프로토콜의 표준을 최대한 활용하여 여러 추가적인 장점을 함께 가져갈 수 있게 해준다.
- HTTP 표준 프로토콜에 따르는 모든 플랫폼에서 사용이 가능하다.
- Hypermedia API의 기본을 충실히 지키면서 범용성을 보장한다
- REST API 메시지가 의도하는 바를 명확하게 나타내므로 쉽게 파악이 가능하다
- 여러가지 서비스 디자인에서 생길 수 있는 문제를 최소화한다
- 서버와 클라이언트의 역할을 명확하게 분리한다
단점
- 표준이 존재하지 않는다
- HTTP Method 형태가 제한적이다
- GET, POST, PUT, DELETE
- 브라우저를 통해 테스트할 일이 많은 서비스라면 쉽게 고칠 수 있는 URL보다 Header 값이 왠지 더 어렵게 느껴진다
- 구형 브라우저가 아직 제대로 지원해주지 못하는 부분이 존재한다
- PUT, DELETE를 사용하지 못한다
- pushState를 지원하지 않는다
REST가 필요한 이유
- 애플리케이션 분리 및 통합
- 다양한 클라이언트의 등장
- 최근의 서버 프로그램은 다양한 브라우저와 안드로이드폰, 아이폰과 같은 모바일 디바이스에서도 통신을 할 수 있어야한다
REST 구성 요소
자원(Resource) : URI
- 모든 자원에 고유한 ID가 존재한다, 이 자원은 Server에 존재한다.
- 자원을 구별하는 ID는 '/groups/:group_id' 와 같은 HTTP URI다
- Client는 URI를 이용해서 자원을 지정하고 해당 자원의 상태(정보)에 대한 조작을 Server에 요청한다
행위(Verb) : HTTP Method
- HTTP 프로토콜의 Method를 사용한다
- HTTP 프로토콜은 GET, POST, PUT, DELETE 와 같은 메서드를 제공한다
표현(Representaion of Resource)
- Client가 자원의 상태(정보)에 대한 조작을 요청하면 Server는 이에 적절한 응답(Representation)을 보낸다
- REST에서 하나의 자원은 JSON, XML, TEXT, RSS 등 여러 형태의 Representation으로 나타내어 질 수 있다.
- JSON 혹은 XML를 통해 데이터를 주고 받는 것이 일반적이다
REST의 특징 6가지
Uniform Interface (유니폼 인터페이스)
- Uniform Interface는 URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일을 말한다
Stateless(무상태성)
- REST는 무상태성 성격을 갖는다.
- 작업을 위한 상태 정보와 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않는다.
- API 서버는 들어오는 요청만 처리하면된다
- 서버의 자유도가 높아지고 서버에서 불필요한 정보를 관리하지 않음으로써 구현이 단순해진다
Cacheable(캐시 가능)
- REST의 가장 큰 특징 중 하나는 HTTP라는 기존 웹표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용이 가능하다. 따라서 HTTP가 가진 캐싱 기능이 적용 가능하다. HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능하다
Self-desccriptiveness(자체 표현 구조)
- REST의 또 다른 큰 특징중 하나는 REST API 메시지만 보고도 이를 쉽게 이해 할 수 있는 자체 표현 구조로 되어 있다
Client -Server 구조
- REST 서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할이 확실히 구분되기 때문에 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로간 의존성이 줄어들게 된다.
계층형 구조
- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간매체를 사용할 수 있게 한다.
REST API 디자인 가이드
중요 항목 2가지
- 첫 번째, URI는 정보의 자원을 표현해야한다
- 두 번째, 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다
REST API 중심 규칙
URI는 정보의 자원을 표현해야한다. (리소스명은 동사보다 명사를 사용)
잘못된 예
GET /members/delete/1URI는 자원을 표현하는데 중점을 두어야한다. delete와 같은 행위에 대한 표현이 들어가서는 안된다
자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE 등)로 표현
올바른 예
DELETE /members/1회원 정보 GET
GET /members/show/1 (x)
GET /members/1 (o)회원 정보 INSERT
GET /members/insert/2 (x) - GET 메서드는 리소스 생성에 맞지 않는다
POST /members/2 (o)[참고] HTTP METHOD의 알맞은 역할
POST, GET, PUT, DELETE 4가지의 Method를 가지고 CRUD를 할 수 있다
PATCH도 사용가능하다
POST
-
POST를 통해 URI를 요청하면 리소스를 생성
멱등성 (X), 안전 (X)
-
여러 번 호출할 경우, 여러 열을 추가한다
POST /add_row HTTP/1.1 POST /add_row HTTP/1.1 -> 2행 추가 POST /add_row HTTP/1.1 -> 3행 추가
-
특징
- POST 메서드 요청은 요청 본문 및 쿼리 문자열에서 입력을 가져온다
- POST 메서드를 사용하여 전달 된 데이터는 브라우저 URL의 queryParam에 표시되지 않는다
- 데이터 길이 전송에 제한이 없다
- 로그인 정보와 같은 민감한 기밀 정보를 서버에 안전하게 전달할 수 있도록 도와준다
장점
- 리소스 URI를 확인하는데 도움이된다
- 새 리소스 위치 헤더를 지정하는 것은 위치 헤더를 사용하여 매우 쉽다
- URI로 식별되는 새 리소스로 엔티티를 수락하는 요청을 보낼 수 있다
- 사용자 생성 데이터를 웹 서버로 보낼 수 있다.
- URL에 보관해야하는 리소스에 대해 전혀 모를 때 매우 유용하다
- 리소스의 URL 생성을 제어하는 서버가 필요할 때 POST를 사용한다
- POST는 요청이 브라우저 기록에 남아있지 않으므로 안전한 방법이다
- POST를 사용하여 손쉽게 많은 양의 데이터를 전송할 수 있다.
- 데이터를 비공개로 유지할 수 있다.
- ASCII 데이터 뿐 아니라 바이너리를 전송하는데 사용할 수 있다.
단점
- POST Method에서 보낸 데이터가 URL 에 표시되지 않으므로 데이터를 저장할 수 없다
- 브라우저 기록에서 POST Request 을 볼 수 없다
- 많은 방화벽 설정과 호환되지 않는다
- spaces, tabs, carnage returns 등 사용할 수 없다
- 큰 바이너리 파일을 업로드할 때 많은 시간이 걸린다
GET
-
GET을 통해 해당 리소스를 조회
-
리소스를 조회하고 해당 도큐먼트에 대한 정보를 가져온다
멱등성 (O), 안전 (O), 캐싱 (O)
- 여러 번 연속해서 호출해도 클라이언트가 받는 응답은 동일하다
특징
- GET 메소드의 길이가 제한된다 (255자)
- 브라우저의 주소 표시 줄에서 데이터를 검색하는데만 사용할 수 있다.
- 방법을 사용하면 데이터를 쉽게 저장할 수 있다.
장점
- GET 메서드는 Request URI(Uniform Resource Identifier)로 식별되는 정보를 검색할 수 있다
- GET Request는 브라우저 기록에서 볼 수 있다.
- HTML 양식의 결과를 저장할 수 있다.
- GET 메서드를 사용하여 필요한 데이터를 쉽게 요청할 수 있다
단점
- GET은 워드 문서나 이미지를 보내는 데 사용할 수 없다
- GET Request는 데이터 검색에만 사용할 수 있다
- GET Method는 사용자 이름 및 비밀번호와 같은 민감한 정보를 전달하는 데 사용할 수 없다
- URL의 길이는 제한되어 있다
- GET Method를 사용하는 경우 브라우저는 URL에 데이터를 추가한다
- GET에서 queryString 값을 쉽게 북마크 할 수 있다.
GET, POST 주요 차이점 :
- GET 메서드에서는 값이 URL에 표시되고 POST 메서드에서는 값이 URL에 표시되지 않습니다.
- GET은 일반적으로 길이에 제한이 있지만 브라우저마다 다르다, POST는 HTTP 본문을 통해 제출되기 때문에 값의 길이에 제한이 없습니다.
- GET 메소드는 문자열 데이터 유형 만 지원하는 반면 POST 메소드는 문자열, 숫자, 이진 등과 같은 다양한 데이터 유형을 지원합니다.
- GET 요청은 종종 캐시 가능한 반면 POST 요청은 거의 캐시되지 않습니다.
- GET 성능은 POST에 비해 더 좋습니다.
PUT
-
PUT을 통해 해당 리소스를 수정한다.
-
리소스 전체를 수정할때 사용
멱등성 (O), 안전 (X), 캐싱 (X)
- 여러 번 연속으로 보내도 같은 효과를 보인다.
DELETE
-
DELETE를 통해 리소스를 삭제한다
멱등성 (O) , 안전 (X), 캐싱 (X)
-
상태코드는 응답마다 다를 수 있지만 멱등성을 가진다
DELETE /idX/delete HTTP/1.1 -> Returns 200 idX가 존재할때 DELETE /idX/delete HTTP/1.1 -> Returns 404 삭제 됐다 DELETE /idX/delete HTTP/1.1 -> Returns 404
-
PATCH
-
PATCH를 통해 리소스를 부분으로 수정한다
멱등성 (O, X)
- PATCH 요청이 다른 결과를 야기할 수도 있다.
- PATCH를 PUT과 같은 방식으로 사용함으로써 멱등성을 가지게 할 수 있다.
-
PATCH (혹은
PUT) 는 다른 리소스에게 부수효과(side- effects)를 일으킬 가능성이 있다. -
서버가 PATCH를 지원하는지 알 수 있게끔 하기 위해 , 서버는
Allow리스트 혹은Access-Control-Allow-Methods(for CORS) 응답 헤더를 통해 이를 명시할 수 있다.
멱등성
- 동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이 같은 효과를 지니고, 서버의 상태도 동일하게 남을 때, 해당 HTTP 메서드가 멱등성을 가졌다고 한다. 다른 말로는 멱등성 메서드에는 통계 기록 등을 제외하면 어떠한 부수 효과도 존재해서는 안된다. 올바르게 구현한 경우 GET, HEAD, PUT, DELETE 메서드는 멱등성을 가지며, POST, PATCH메서드는 그렇지 않다
- 멱등성을 따질때는 실제 서버의 벡엔드 상태만 보면 되며, 각 요청에서 반환하는 응답 코드는 다를 수 있다. 첫 번째
DELETE요청이200을 반환한다면, 그 이후는 아마404를 반환할 것이다.DELETE가 멱등성을 가진다는 것은 REST API에서는DELETE메서드를 사용해 "목록의 마지막 항목 제거" 기능을 구현해서는 안된다
URI 설계 시 주의점
1) 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용
http://www.example.com/api/posts2) URI 마지막 문자로 슬래시(/)를 포함하지 않는다.
URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다
3) 하이픈(-)은 URI 가독성을 높이는데 사용
URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있다.
4) 언더바(_)는 사용 하지않는다
글꼴에 따라 다르긴하지만 언더바는 보기 어렵거나 언더바때문에 문자가 가려지기도한다. 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋다(가독성)
5) 소문자 사용
URI 경로에 대문자 사용은 피하도록해야한다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문이다. RFC3986(URI 문법형식) 은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하기 때문이다
6) 파일 확장자는 URI에 포함시키지 않는다.
http://www.example.com/api/posts/photo.jpg (x)REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. Accept header를 사용하도록하자
GET / members/1/photo HTTP/1.1 Host: www.example.com Accept: image/jpg리소스 간의 관계를 표현하는 방법
- REST 리소스 간에는 연관 관계가 있을 수 있고, 이런 경우 다음과 같은 표현 방법으로 사용합니다.
/리소스명/리소스 ID/관계가 있는 다른 리소스명
ex) GET : /users/{userid}/devices (일반적으로 소유 'has'의 관계를 표현할 때)만약에 관계명이 복잡하다면 이를 서브 리소스에 명시적으로 표현하는 방법이 있다. 예를 들어 사용자가 '좋아하는' 디바이스 목록을 표현해야 할 경우 다음과 같은 형태로 사용될 수 있다.
GET : /users/{userid}/likes/devices (관계명이 애매하거나 구체적 표현이 필요할 때)자원을 표현하는 Collection과 Document
Collection과 Document에 대해 알면 URI 설계가 한 층 더 쉬워진다. DOCUMENT는 단순히 문서로 이해해도 되고, 한 객체라고 이해해도된다. 컬렉션은 문서들의 집합, 객체들의 집합이라고 생각하면 이해하는데 편하다. 컬렉션과 도큐먼트는 모두 리소스라고 포현할 수 있고 URI에 표현된다.
예)
http://api.example.com/boards/book위 URI를 보면 boards라는 컬렉션과 book라는 도큐먼트로 표현되고 있다
Reference
'프로젝트 > 기타' 카테고리의 다른 글
| DB에 기본값을 줄지 Server단에서 기본값을 줄지? (0) | 2021.04.30 |
|---|---|
| Gradle Build, Coverage 오류 (2) | 2021.04.06 |