RESTful API
참고
https://prohannah.tistory.com/156
https://restfulapi.net/resource-naming/
REST, RESTful
REST는 REpresentational State Transfer의 약자이자 분산 하이퍼미디어 시스템의 아키텍처 스타일입니다. 데이터와 기능은 리소스로 간주되며 URI를 사용하여 액세스됩니다.
다른 아키텍처 스타일과 마찬가지로 REST도 그 가이드 원칙과 제약이 있습니다. 6가지 원칙 또는 제약 조건이 충족되면 RESTful하다고 할 수 있습니다.
RESTful API를 위한 원칙과 제약조건
1.1. 균일한 인터페이스(Uniform Interface)
전체 시스템 아키텍처를 단순화하고 상호 작용의 가시성을 개선할 수 있습니다.
다중 아키텍처 제약은 균일한 인터페이스를 얻고 구성 요소의 동작을 안내하는 데 도움이 됩니다.
다음과 같은 네 가지 제약 조건으로 REST 인터페이스를 균일하게 할 수 있습니다:
▶ Identification of resources – 인터페이스는 클라이언트와 서버 간의 상호 작용에 관련된 각 리소스를 고유하게 식별해야 합니다.
▶ Manipulation of resources through representations – 서버 응답에서 리소스가 균일한 표현을 가져야 합니다. API 소비자는 이러한 표현을 사용하여 서버의 리소스 상태를 수정해야 합니다.
▶ Self-descriptive messages – 각 리소스 표현은 메시지를 처리하는 방법을 설명하기에 충분한 정보를 전달해야 합니다. 또한 클라이언트가 리소스에 대해 수행할 수 있는 추가 작업에 대한 정보도 제공해야 합니다.
▶ Hypermedia as the engine of application state – 클라이언트는 응용 프로그램의 초기 URI만 가지고 있어야 합니다. 클라이언트 응용 프로그램은 하이퍼링크를 사용하여 다른 모든 리소스와 상호 작용을 동적으로 구동해야 합니다.
1.2. 클라이언트-서버(Client-Server)
클라이언트와 서버 설계 패턴은 관심사를 분리하도록 강요하며, 이는 클라이언트와 서버 구성요소가 독립적으로 발전하도록 도와줍니다.
사용자 인터페이스 관심사(클라이언트)와 데이터 스토리지 관심사(서버)를 분리하여 여러 플랫폼에 걸쳐 사용자 인터페이스의 휴대성을 개선하고 서버 구성 요소를 단순화하여 확장성을 개선합니다.
클라이언트와 서버가 진화하는 동안 클라이언트와 서버 간의 인터페이스/계약이 깨지지 않도록 해야 합니다.
1.3 무상태(Stateless)
클라이언트에서 서버로 요청할 때마다 요청을 이해하고 완료하는 데 필요한 모든 정보를 포함해야 합니다.
서버는 이전에 저장된 서버의 컨텍스트 정보를 이용할 수 없습니다.
이러한 이유로 클라이언트 응용프로그램은 세션 상태를 완전히 유지해야 합니다.
1.4. 캐시 가능(Cacheable)
응답 자체에 캐시 가능 또는 캐시 불가능으로 암시적 또는 명시적으로 레이블을 지정해야 합니다.
응답이 캐시 가능한 경우 클라이언트 응용 프로그램은 해당 요청 및 지정된 기간에 대해 나중에 응답 데이터를 재사용할 수 있는 권한을 가집니다.
1.5. 레이어드 시스템(Layered System)
구성요소 동작을 제한함으로써 아키텍처를 계층화된 계층으로 구성할 수 있게 합니다.
예를 들어 계층화된 시스템에서는 각 구성 요소가 상호 작용 중인 직접 계층 이상을 볼 수 없습니다.
1.6. 주문형 코드(선택 사항) (Code on Demand (Optional))
REST는 또한 애플릿이나 스크립트 형태의 코드를 다운로드하여 실행함으로써 클라이언트 기능을 확장할 수 있습니다.
RESTful API 네이밍 방식
- 가독성을 위해 `-`(하이픈)을 사용하라
- 소문자를 사용하라
Schem과 HOST에만 대소문자 구별이 없고, 이 외에는 대소문자가 구별된다.
- CRUD 함수명을 사용하지 마라
URI는 어떤 동작이 수행되는 지 가르키는 게 아니라, 리소스를 가르키는 것이다.
리소스에 대한 작업은 HTTP Method를 이용하도록 한다.
- 필터를 위해 쿼리 파라미터를 사용해라
Resource(or Reperesentation)에 대한 정렬, 필터링, 페이징은 신규 API를 생성하지 않고 쿼리 파라미터를 활용해라.