참고
RESTful API란 무엇인가요? aws
구글 REST API 작성 가이드라인
마이크로소프트 REST API 작성 가이드라인
asw의 RESTful API란 무엇인가요?에 관한 문서를 정리하였습니다.
RESTful API란?
RESTful API는 두 컴퓨터 시스템이 인터넷을 통해 정보를 안전하게 교환하기 위해 사용하는 인터페이스이다.
API란?
API: Application Programming Interface
애플리케이션 프로그래밍 인터페이스는 다른 소프트웨어 시스템과 통신하기 위해 따라야 하는 규칙을 정의한다.
개발자는 다른 애플리케이션이 프로그래밍 방식으로 애플리케이션과 통신할 수 있도록 API를 표시하거나 생성한다.
클라이언트
- 웹/앱에서 정보에 엑세스하려는 사용자이다.
- 클라이언트는 API를 사용하는 사람이거나 소프트웨어 시스템일 수 있다.
ex) 개발자는 날씨 시스템에서 날씨 데이터에 엑세스하는 프로그램을 작성할 수 있다. 또는 사용자가 날씨 웹 사이트를 직접 방문할 때 브라우저에서 동일한 데이터에 엑세스 할 수 있다.
리소스
- 리소스는 다양한 애플리케이션이 클라이언트에게 제공하는 정보이다.
- 리소스는 이미지, 동영상, 텍스트, 숫자 또는 모든 유형의 데이터일 수 있다.
- 클라이언트에 리소스를 제공하는 시스템을 서버라고도 한다.
- 조직은 API를 사용하여 리소스를 공유하고 보안, 제어 및 인증을 유지하면서 웹서비스를 제공한다.
- 또한 API는 특정 내부 리소스에 액세스 할 수 있는 클라이언트를 결정하는 데 도움이 된다.
REST(Representational State Transfer) API
웹 애플리케이션은 HTTP 메서드를 이용해 서버와 통신하고
클라이언트와 서버는 HTTP 통신을 할 때 어떤 요청을 보내고 받는지에 따라 메서드의 사용이 달라진다.
REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현한다.
Restful API 클라이언트 요청에 포함되어 있는 것들
Restful API에는 다음과 같은 주요 구성요소를 포함하는 요청이 필요하다.
고유 리소스 식별자
- 서버는 고유한 리소스 식별자로 각 리소스를 식별한다.
- REST 서비스의 경우 서버는 일반적으로 URL(Uniform Resource Locator)을 사용하여 리소스 식별을 수행한다.
- URL은 리소스에 대한 경로를 지정한다. URL은 웹 페이지를 방문하기 위해 브라우저에 입력하는 웹 사이트 주소와 유사하다.
- URL은 요청 엔드포인타라고도 하며 클라이언트가 요구하는 사항을 서버에 명확하게 지정한다.
메서드
- 개발자는 종종 Hypertext Transfer Protocol(HTTP)을 사용하여 RESTful API를 구현한다. HTTP 메서드는 리소스에 수행해야 하는 작업을 서버에 알려준다.
일반적인 HTTP 메서드는 아래와 같다.
GET: 클라이언트는
GET을 사용하여 서버의 지정된 URL에 있는 리소스에 엑세스 한다.GET요청을 캐싱하고 RESTful API 요청에 파라미터를 넣어 전송하여 전송 전에 데이터를 필터링하도록 서버에 지시할 수 있다.POST: 클라이언트는
POST를 사용하여 서버에 데이터를 전송한다. 여기에는 요쳥과 함께 데이터 표현이 포함된다. 동일한POST요청을 여러 번 전송하면 동일한 리소스를 여러 번 생성하는 부작용이 있다.PUT: 클라이언트는
PUT을 사용하여 서버의 기존 리소스를 업데이트 한다.POST와 달리 RESTful 웹 서비스에서 동일한PUT요청을 여러 번 전송해도 결과는 동일하다.DELETE: 클라이언트는
DELETE요청을 사용하여 리소스를 제거한다.DELETE요청은 서버 상태를 변경할 수 있다. 하지만 사용자에게 적절한 인증이 없으면 요청은 실패한다.
HTTP 메서드를 사용할 때 지켜야 할 규칙
| 메서드 | 규칙 |
|---|---|
GET | 서버의 데이터를 변화시키지 않는 요청에서 사용해야 한다. |
POST | 요청마다 새로운 리소스를 생성한다. |
PUT | 요청마다 같은 리소스를 반환한다. 매 요청마다 같은 리소스를 반환하는 특징을 멱등(idempotent)하다고 하는데 멱등성을 가지는 메서드 PUT과 멱등성을 가지지 않는 POST를 잘 구분해서 사용해야 한다.교체의 용도로 사용 |
PATCH | 수정의 용도로 사용 |
HTTP 헤더
- 요청 헤더는 클라이언트와 서버 간에 교환되는 메타데이터이다.
ex) 요청 헤더는 요청 및 응답의 형식을 나타내고 요청 상태 등에 댛나 정보를 제공한다.
데이터
REST API 요청에는 POST, PUT 및 기타 HTTP 메서드가 성공적으로 작동하기 위한 데이터가 포함될 수 있다.
파라미터
RESTful API 요청에는 수행해야 할 작업에 대한 자세한 정보를 서버에 제공하는 파라미터가 포함될 수 있다.
다음은 몇 가지 파라미터 유형이다.
- URL 세부 정보를 지정하는 경로 파라미터
- 리소스에 대한 추가 정보를 요청하는 쿼리 파라미터
- 클라이언트를 빠르게 인증하는 쿠키 파라미터
Restful API 인증 방법이란?
RESTful 웹 서비스는 응답을 보내기 전에 먼저 요청을 인증해야 한다.
인증은 신원을 확인하는 프로세스로 예를 들어 신분증이나 운전면허증을 제시하여 신원을 증명할 수 있다.
마찬가지로 RESTful 서비스 클라이언트는 신뢰를 구축하기 위해 서버에 자신의 신원을 증명해야 한다.
RESTful API의 일반적은 인증방법 4가지
HTTP 인증
HTTP REST API를 구현할 때 직접 사용할 수 있는 일부 인증 체계를 정의하고 이러한 체계 중 두 가지를 알아보면 다음과 같다.
기본 인증
- 기본 인증에서 클라이언트는 요청 헤더에 사용자 이름, 암호를 넣어 전송한다.
- 안전한 전송을 위해 이 값들을 64자의 세트로 변환하는 인코딩 기술인 base64로 인코딩한다.
전달자 인증
- 전달자(bearer) 인증이라는 용어는 토큰 전달자에 대한 액세스 제어를 제공하는 프로세스를 나타낸다.
- 일반적으로 전달자 토큰은 서버가 로그인 요청에 대한 응답으로 생성하는 암호화된 문자열이다.
- 클라이언트는 리소스에 액세스하기 위해 요청 헤더에 토큰을 넣어 전송한다.
API key
- API Key는 REST API 인증을 위한 또 다른 옵션으로 이 접근 방식에서 서버는 고유하게 생성된 값을 최초 클라이언트에 할당한다.
- 클라이언트는 리소스에 액세스하려고 할 때마다 이 고유한 API key를 사용하여 본인을 검증한다.
- API key의 경우 클라이언트가 이 키를 전송해야 해서 네트워크 도난에 취약하기 때문에 덜 안전하다.
OAuth
- OAuth는 모든 시스템에 대해 매우 안전한 로그인 액세를 보장하기 위해 암호와 토큰을 결합한다.
- 서버는 먼저 암호를 요청한 다음 권한 부여 프로세스를 완료하기 위해 추가 토큰을 요청한다.
- 특정 범위와 수명으로 언제든지 토큰을 확인할 수 있다.
RESTful API 서버 응답에 포함된 것들
REST 원칙에 따라 서버 응답에 다음과 같은 주요 구성 요소를 포함해야 한다.
상태 표시줄
- 상태 표시줄에는 요청 성공 or 실패를 알리는 3자리 상태코드가 있다.
ex) 2XX 코드는 성공을 나타내고, 4XX 및 5XX 코드는 오류를 나타낸다. 3XX 코드는 URL 리디렉션을 나타낸다.
몇 가지 일반적인 상태 코드
200: 일반 성공 응답
201: POST 메서드 성공 응답
400: 서버가 처리할 수 없는 잘못된 요청
404: 리소르를 찾을 수 없음
더 많은 상태코드는 mdn에서 자세하게 알아볼 수 있다.
HTTP 상태 코드
메시지 본문
- 응답 본문에는 리소스 표현이 포함된다.
- 서버는 요청 헤더에 포함된 내용을 기반으로 적절한 표현 형식을 선택한다.
- 클라이언트는 데이터 작성 방식을 일반 텍스트로 정의하는 XML or JSON 형식으로 정보를 요청할 수 있다.
ex) 클라이언트가 A라는 사람의 이름과 나이를 요청하면 서버는 다음과 같이 JSON 표현을 반환한다.
'{"name": "A", "age": 30}'헤더
응답에는 응답에 대한 헤더 or 메타데이터도 포함된다. 이는 응답에 대한 추가 컨텍스트를 제공하고 서버, 인코딩, 날짜 및 콘텐츠 유형과 같은 정보를 포함한다.
