[WEB]REST API

Yewon Jeong·2023년 5월 19일

WEB

목록 보기

1/1

SOAP API : 단순 객체 접근 프로토콜.XML을 사용하여 메시지를 교환.많은 리소스와 대역폭 요구.엄격한 통신규약을 가지고있어
모든 메세지를 보내기 전 알려야함. 과거에 더 많이 사용되었으며 유연성이 떨어지는 API임.(기업용 애플리케이션에서 사용하는 경우가 있음)
REST API :오늘날 웹에서 볼 수 있는 가장 많이 사용되는 API. 데이터를 위해서 리소스에 접근(URL). plain/text, HTML, XML,JSON 형식으로 데이터 교환.
Websocket API: 구독형 API.서버와 클라이언트 간에 연결을 유지하며 실시간으로 데이터를 전송.

REST(REpresentational State Transfer)

REST : 분산 하이퍼미디어 시스템(예:웹)을 위한 아키텍쳐 스타일
사실 오늘날 대부분의 REST API는 REST 규약을 따르지 않고 있다.(self-descriptive,hateoas를 만족하기가 어려움.rest가 아니지만 rest라고 하는 경우가 다반사) 만약 REST 규약을 모두 따른다면 이 API를 RESTful API라고 한다.

“Representational State Transfer” 의 약자로 자원을 이름으로 구분(자원의 표현)하여 해당 자원의 상태(state)를 주고 받는 모든 것을 의미한다. 즉, 자원(resource)의 표현(representation) 에 의한 상태 전달을 의미한다.

REST를 구성하는 것

자원(RESOURCE)-URI

해당 소프트웨어가 관리하는 모든 것. ex 블로그 포스트, 댓글, 사용자 프로필 등
자원을 구분하는 고유한 식별자(Uniform Resource Identifier, URI)로 식별된다.

행위(Verb) - HTTP METHOD

클라이언트가 서버에 요청을 보내어 자원에 대한 조작(Manipulation)을 수행하는 것
행위는 HTTP 메서드(Verb)를 통해 나타낸다.
GET,POST,PUT,DELETE,PATCH

표현(Representations)

자원의 상태에 대한 표현
하나의 자원은 JSON, XML, TEXT 등 여러 형태의 Representation으로 나타내어 질 수 있다.
일반적으로는 JSON(JavaScript Object Notation)이나 XML(Extensible Markup Language) 형식을 사용

REST 원칙들

client-server(서버-클라이언트 구조)

클라이언트와 서버가 독립적으로 개발되고 관리된다.client-server 모델은 각 역할에 대한 독립성을 제공하므로, 각각의 구성 요소를 독립적으로 확장할 수 있다. 서버 측에서는 데이터베이스나 로직을 추가하거나 변경할 수 있으며, 클라이언트 측에서는 새로운 UI 요소나 기능을 추가하거나 변경할 수 있다.

stateless

서버가 클라이언트의 상태를 유지하지 않는 것을 의미
서버의 부담을 줄이고 확장성을 향상시키는 장점
클라이언트의 요청에 필요한 모든 정보가 요청 자체에 포함되어야 한다. 서버는 각각의 요청을 독립적으로 이해하고 처리할 수 있어야 한다.

cache

웹 표준 HTTP 프로토콜을 그대로 사용하므로 웹에서 사용하는 기존의 인프라를 그대로 활용
동일한 요청이 반복될 때 클라이언트나 중간 서버에서 이전에 받았던 응답을 재사용
HTTP 프로토콜 표준에서 사용하는 Last-Modified 태그나 E-Tag를 이용하면 캐싱 구현이 가능
- Cache-Control: 서버의 응답을 어떻게 캐시할지 지시
- ETag: 응답 헤더는 특정 버전의 리소스를 식별하는 식별자. 웹 서버가 내용을 확인하고 변하지 않았으면, 웹 서버로 full 요청을 보내지 않기 때문에, 캐쉬가 더 효율적이게 되고, 대역폭도 아낄 수 있다.

uniform interface

클라이언트와 서버 간의 상호 작용을 일관되고 통일된 방식으로 설계
HTTP 표준 프로토콜을 따르는 모든 플랫폼에서 사용 가능
이 규약을 모두 지키는 것은 비효율을 유발할 수 있다.
Self - descriptiveness
- 클라이언트와 서버 간의 상호 작용을 위한 메시지는 그 자체로 어떤 동작을 수행해야 하는지 명확하게 설명할 수 있어야 한다.(메시지 포맷,메타데이터,URI,표현)
- host 헤더에 도메인명(하나의 ip 주소로 복수의 도메인명이 존재할 수 있기때문에 ip 주소만으로는 요청대상을 찾아낼 수 없다.) 기재 필요(HTTP/1.1 부터 HOST 헤더 필수화)
- 캐시 관련 헤더를 통한 캐시 전략 지정
hateoas
- 클라이언트에게 애플리케이션의 상태를 전달하고 상호 작용할 수 있는 링크를 제공(하이퍼미디어 링크를 포함)
- 이 링크는 클라이언트가 현재 상태에서 수행할 수 있는 다음 가능한 동작을 나타냄
- 클라이언트는 이 링크를 따라가며 애플리케이션의 상태 전이를 진행
- 백엔드 서버는 지키기 어려움.

layered system

일반적으로 클라이언트와 서버 사이에 여러 개의 중간 계층이 존재할 수 있다.
API Server는 순수 비즈니스 로직을 수행하고 그 앞단에 보안, 로드밸런싱, 암호화, 사용자 인증 등을 추가하여 구조상의 유연성을 줄 수 있다.
성능, 보안, 확장성 등을 개선할 수 있다.

code-on-demand (optional)

서버에서 클라이언트로 코드를 전송하여 클라이언트에서 실행되도록 하는 개념을 의미.(ex CSR)
서버와의 의존성을 줄이는 데 도움

REST API 디자인 가이드

Document : 객체 인스턴스나 데이터베이스 레코드와 유사한 개념(단순히 문서 or 한 객체)

Colllection : 서버에서 관리하는 디렉터리라는 리소스(문서들의 집합 or 객체들의 집합)

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

각 자원은 고유한 식별자(URI)를 가지고 있고,URI는 정보의 자원을 표현해야 한다.
- 도큐먼트 이름으로는 단수 명사를 사용
- 스토어,컬렉션 이름으로는 복수 명사 사용
자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE)로 표현한다.

ex)

http:// restapi.example.com/sports/soccer/players/13

자원(Resource) 기반 설계 : REST API는 자원을 중심으로 설계되어야 한다. 각 자원은 고유한 식별자(URI)를 가지고 있으며, 자원에 대한 CRUD(Create, Read, Update, Delete) 동작을 수행한다. delete와 같은 행위에 대한 표현이 들어가서는 안된다.
명사형으로 자원을 표현:REST API의 URI는 명사형으로 자원을 표현 예를 들어, /users는 사용자 자원을 나타내며, /products는 제품 자원을 나타낸다.
HTTP 메서드 활용:HTTP 메서드(GET, POST, PUT, DELETE 등)를 적절하게 활용하여 동작
계층적인 URI 경로 설계: URI 경로는 계층적인 구조를 가질 수 있으며, 관련된 자원 간의 관계를 나타낼 수 있다.(슬래시 구분자(/)는 계층 관계를 나타내는 데 사용) 예를 들어, /users/{userId}/posts는 특정 사용자의 게시물 자원을 나타낸다.(+URI 마지막 문자로 슬래시(/)를 포함하지 않는다.)
필터링과 정렬: 컬렉션 자원에 대해 필터링이나 정렬을 적용해야 할 경우, 쿼리 매개 변수를 활용하여 요청을 구성. 자원의 필터링을 위해 새로운 api를 만들지 않는다.
상태 코드 사용 : 요청의 성공, 실패, 리다이렉션 등을 나타내기 위해 적절한 HTTP 상태 코드를 사용
버전 관리 : API의 변경이 필요한 경우, 버전 관리를 고려

+) 추가

하이픈(-)은 URI 가독성을 높이는데 사용
밑줄( _ ) 은 URI에 사용하지 않는다.
URI 경로에는 소문자가 적합하다.
파일 확장자는 URI에 포함시키지 않는다.

HTTP 응답 상태 코드

잘 설계된 REST API는 URI만 잘 설계된 것이 아닌 그 리소스에 대한 응답을 잘 내어주는 것까지 포함되어야 한다. 정확한 응답의 상태코드만으로도 많은 정보를 전달할 수 있다.

상태코드
200 OK	클라이언트의 요청을 정상적으로 수행함 (주로 GET 작업 시)
201 Created	클라이언트가 어떠한 리소스 생성을 요청, 해당 리소스가 성공적으로 생성됨(POST를 통한 리소스 생성 작업 시)
204 No Content	성공 상태 응답 코드는 요청이 성공했으나 클라이언트가 현재 페이지에서 벗어나지 않아도 된다

상태코드
400 Bad Request	클라이언트의 요청이 부적절 할 경우 사용하는 응답 코드
401 Unauthorized:	클라이언트가 인증되지 않은 상태에서 보호된 리소스를 요청했을 때 사용하는 응답 코드
	(로그인 하지 않은 유저가 로그인 했을 때, 요청 가능한 리소스를 요청했을 때)
403 Forbidden	유저 인증상태와 관계 없이 응답하고 싶지 않은 리소스를 클라이언트가 요청했을 때 사용하는 응답 코드
	(403 보다는 400이나 404를 사용할 것을 권고. 403 자체가 리소스가 존재한다는 뜻이기 때문에)
404 Not Found	유요청한 자원이 서버에서 찾을 수 없음
405	클라이언트가 요청한 리소스에서는 사용 불가능한 Method를 이용했을 경우 사용하는 응답 코드

상태코드
301	클라이언트가 요청한 리소스에 대한 URI가 변경 되었을 때 사용하는 응답 코드
	(응답 시 Location header에 변경된 URI를 적어 줘야 한다.)
500	서버에 문제가 있을 경우 사용하는 응답 코드

참고
https://deview.kr/2017/schedule/212
https://gmlwjd9405.github.io/2018/09/21/rest-and-restful.html
https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Cache-Control
https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/ETag
https://meetup.nhncloud.com/posts/92
https://developer.mozilla.org/ko/docs/Web/HTTP/Status/204

Yewon Jeong

일단 하는 중