REST API란

REST API: REST(REpresentational State Transfer, 대표 상태 이전) 아키텍처 스타일의 디자인 원칙을 준수하는 API이다.

• WWW과 같은 분산 하이퍼미디어(비선형 매체) 시스템을 위한 소프트웨어 아키텍처의 한 형식이다.
  ⇒ 쉽게 말해 두 컴퓨터 시스템이 인터넷을 통해 교환하기 위해 사용하는 인터페이스를 뜻한다.
• REST 아키텍처를 구현하는 웹 서비스를 RESTful 웹 서비스라고 한다.

API: 애플리케이션이나 디바이스가 서로 간에 연결하여 통신할 수 있는 방법을 정의 하는 규칙 세트이다.

즉 REST API는 REST 아키텍처 스타일을 따르는 API를 말한다.

REST 아키텍처 스타일의 6가지 제한 조건

REST API는 거의 모든 프로그래밍 언어를 사용하여 개발이 가능하며 다양한 데이터 포맷을 지원한다. 유일한 요구사항은 다음의 6가지 REST 디자인 원칙에 맞아야한다.

1. 인터페이스 일관성
   1. 요청이 어디에서 오는지와 무관하게 동일한 리소스에 대한 모든 API요청은 동일하게 보여야한다.
   2. REST API는 사용자의 이름이나 이메일 주소등의 동일한 데이터 조각이 오직 하나의 URI(Uniform Resource Identifier, 네트워크 상 자원을 가리키는 일종의 고유 식별자)에 속함을 보장해야한다.
2. 무상태(Stateless)
   • 각 요청 간 클라이언트 콘텍스트가 서버에 저장되어서는 안 된다.
   • 서버가 이전의 모든 요청과 독립적으로 모든 클라이언트 요청을 완료하는 통신 방법을 말하며 클러이언트는 임의의 순서로 리소스를 요청할 수 있으며 모든 요청은 무상태이거나 다른 요청과 분리된다.
3. 계층화 시스템
   • 클라이언트 요청을 이행하기 위해 함께 작동하는 보안, 애플리케이션 및 비즈니스 로직과 같은 여러 계층으로 여러 서버에서 실행되도록 RESTful 웹 서비스를 설계할 수 있다.
   • 클라이언트는 보통 대상 서버에 직접 연결되었는지, 또는 중간 서버를 통해 연결되었는지를 알 수 없다. 즉 계층은 클라이언트가 볼 수 없다.
4. 캐싱 가능성
   • 가급적이면 클라이언트 또는 서버측에서 캐싱할 수 있어야한다. 서버 응답에는 전달된 리소스에 대해 캐싱이 허용되는지 여부에 대한 정보도 포함되어야한다. ⇒ 이의 목적은 서버측의 확장성 증가와 함께 클라이언트 측 성능 향상을 동시에 얻는 것이다.
   • RESTful 웹 서비스는 서버 응답 시간을 개선하기 위해 클라이언트 또는 중개자에 일부 응답을 저장하는 프로세스인 캐싱을 지원한다. (ex. 모든 페이지에 header, footer가 존재하는 웹사이트를 방문할 때 새로운 페이지로 이동할 때마다 header, footer 속 이미지를 재전송할 경우가 있다. 이때 이미지를 캐싱하여 재전송을 방지한다.)
5. 코드 온디맨드(옵션):
   • 일반적으로 정적 리소스를 전송하지만 특정한 경우에는 응답에 실행 코드를 포함할 수 있다.
   • 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트 기능을 일시적으로 확장하거나 사용자 지정할 수 있다.(ex. 웹 사이트에서 등록 양식을 작성하면 브라우저는 잘못된 전화번호와 같은 입력 실수를 강조 표시가 되도록 할 수 있는데 이때 서버에서 전송한 코드로 인해 이 작업을 수행할 수 있다.)
6. 클라이언트/서버 구조
   • 아키텍처를 단순화 시키고 작은 단위로 분리(decouple)함으로써 클라이언트와 서버의 각 파트가 독립적으로 개선될 수 있도록 한다.

RESTful API의 장점

• 확장성
  • REST가 클라이언트-서버 상호 작용을 최적화하기 때문에 효율적으로 크기 조정이 가능하다.
  • 무상태 조건으로 인해 서버가 과거 클라이언트 요청 정보를 유지할 필요가 없어 서버 로드를 제거한다.
  • 잘 관리된 캐싱은 일부 클라이언트-서버 상호 작용을 부분적 또는 완전히 제거한다.
    ⇒ 성능을 저하시키는 통신 병목 현상을 일으키지 않으면서 확장성을 지원한다.
• 유연성
  • 완전한 클라이언트-서버 분리를 지원하여 서버 애플리케이션의 플랫폼 또는 기술 변경이 클라이언트 애플리케이션에 영향을 주지 않는다.
• 독립성
  • REST API는 사용되는 기술과 독립적이다. ⇒ API 설계에 영향을 주지 않고 다양한 프로그래밍 언어로 클라이언트 및 서버 애플리케이션을 모두 작성할 수 있다.

REST API 설계 시 중요 항목

1. URI는 정보의 자원을 표현해야한다.
2. 자원에 대한 행위는 HTTP Method(GET, POST, PUT, DELETE - CRUD)로 표현한다.

RESTful API 클라이언트 요청

RESTful API에는 다음과 같은 주요 구성요소를 포함하는 요청이 필요하다.

• 고유 리소스 식별자
  • 서버는 고유한 리소스 식별자로 각 리소스를 식별하는데 REST의 경우 서버는 URL을 사용하여 리소스 식별을 수행한다.
  • URL은 리소스에 대한 경로를 지정하며 이는 웹 사이트 주소와 유사하다.
• 메서드

  • HTTP를 RESTful API를 구현하는 경우가 많은데 HTTP 메서드는 리소스에 수행해야 하는 작업을 서버에 알려준다.

    METHOD	역할
    POST	해당 URI를 요청하면 리소스를 생성한다
    GET	해당 리소스를 조회한다. 리소스를 조회하고 해당 도큐먼트에 대한 자세한 정보를 가져온다
    PUT	해당 리소스를 수정한다
    DELETE	해당 리소스를 삭제한다.

• HTTP 헤더
  • 요청 헤더는 클라이언트와 서버 간에 교환되는 메타데이터이다.(ex. 요청 헤더는 요청 및 응답의 형식을 나타내고 요청 상태 등에 대한 정보를 제공한다.)
  • 데이터
    • REST API 요청에는 POST, PUT, 및 기타 HTTP 메서드가 성공적으로 작동하기 위한 데이터가 포함될 수 있다.
  • 파라미터
    • RESTful API 요청에는 수행해야 할 작업에 대한 자세한 정보를 서버에 제공하는 파라미터가 포함될 수 있다.
    • 파라미터 요청
      • URL 세부정보를 지정하는 경로 파라미터
      • 리소스에 대한 추가 정보를 요청하는 쿼리 파라미터
      • 클라이언트를 빠르게 인증하는 쿠키 파라미터

RESTful API 인증 방법

Restful 웹 서비스는 응답을 보내기 전에 먼저 요청을 인증해야한다, 마찬가지로 RESTful 서비스 클라이언트는 서버에 자신의 신원을 증명해야한다.

HTTP 인증

HTTP는 REST API를 구현할 때 직접 사용할 수 있는 일부 인증 체계를 정의한다.

• 기본 인증: 클라이언트는 요청 헤더에 사용자 이름과 암호를 넣어 전송한다. 안전한 전송을 위해 이 페어를 64자의 세트로 변환하는 인코딩 기술인 base64로 인코딩합니다.
• 전달자 인증: 일반적으로 전달자 토큰은 서버가 로그인 요청에 대한 응답으로 생성하는 암호화된 문자열입니다. 클라이언트는 리소스에 액세스하기 위해 요청 헤더에 토큰을 넣어 전송합니다.

API 키

서버는 고유하게 생성된 값을 최초 클라이언트에 할당하고 클라이언트는 리소스에 액세스하려고 할 때마다 고유한 API 키를 사용하여 본인을 검증한다. 클라이언트가 API 키를 전송해야 하기 때문에 네트워크 도난에 취약하다.

OAuth

모든 시스템에 대해 매우 안전한 로그인 액세스를 보장하기 위해 암호와 토큰을 결합한다. 서버는 먼저 암호를 요청한 다음 권한 부여 프로세스를 완료하기 위해 추가 토큰을 요청한다.

URI 설계 시 주의할 점

---

1. 슬래시 구분자(/)는 계층 관계를 나타내는 데 사용

http://restapi.example.com/houses/apartments (x)
http://restapi.example.com/animals/mammals/whales (O)

2. URI 마지막 문자로 슬래시(/)를 포함하지 않는다.

• URI에 포함되는 모든 글자는 리소스의 유일한 식별자로 사용되어야 하며 URI가 다르다는 것은 리소스가 다르다는 것이고, 역으로 리소스가 다르면 URI도 달라져야 한다.
• REST API는 분명한 URI를 만들어 통신을 해야 하기 때문에 혼동을 주지 않도록 URI 경로의 마지막에는 슬래시(/)를 사용하지 않는다.
  

http://restapi.example.com/animals/mammals/whales/ (x)
http://restapi.example.com/animals/mammals/whales  (O)

3. 하이픈(-)은 URI 가독성을 높이는데 사용

• URI를 쉽게 읽고 해석하기 위해, 불가피하게 긴 URI경로를 사용하게 된다면 하이픈을 사용해 가독성을 높일 수 있다.

4. 밑줄(_)은 URI에 사용하지 않는다.

• 글꼴에 따라 다르긴 하지만 밑줄은 보기 어렵거나 밑줄 때문에 문자가 가려지기도 한다 이런 문제를 피하기 위해 밑줄 대신 하이픈(-)을 사용하는 것이 좋다.

5. URI 경로에는 소문자가 적합하다.

• URI 경로에 대문자 사용은 피하도록 한다. 대소문자에 따라 다른 리소스로 인식하게 되기 때문이다.
• RFC 3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정 하고있다.

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

http://restapi.example.com/members/3/photo.jpg (X)

• REST API에서는 메시지 바디 내용의 포맷을 나타내기 위한 파일 확장자를 URI 안에 포함시키지 않는다. Accept header를 사용한다.
  

GET /members/3/photo HTTP/1.1 Host: restapi.example.com Accept: image/jpg

참고

aws - RESTful API란 무엇입니까?