Rest API

황승우·2023년 2월 12일

web

1. REST(Representational State Transfer)

URI를 통해 자원을 표시하고, HTTP Method를 이용하여 해당 자원의 행위를 규정하여 그 결과를 받는 것을 의미한다

2. REST 특징

Uniform
- URI로 지정한 리소스에 대한 조작을 통일되고 한정적인 인터페이스로 수행하는 아키텍처 스타일
Stateless
- 작업을 위한 상태 정보를 따로 저장하고 관리하지 않음.
- 세션 정보나 쿠키 정보를 별도로 저장하고 관리하지 않기 때문에 API 서버는 들어오는 요청만을 단순히 처리하면 됨.
Cacheable
- HTTP라는 기존 웹 표준을 그대로 사용하기 때문에, 웹에서 사용하는 기존 인프라를 그대로 활용할 수 있어 HTTP가 가진 캐싱 기능 적용이 가능하다.
Self-descriptiveness
- REST API 메시지만 보고도 이를 쉽게 이해할 수 있는 자체 표현 구조
Client - Server 구조
- REST서버는 API 제공, 클라이언트는 사용자 인증이나 컨텍스트(세션, 로그인 정보) 등을 직접 관리하는 구조로 각각의 역할을 확실하게 구분
- 클라이언트와 서버에서 개발해야 할 내용이 명확해지고 서로 간 의존성이 줄어듬.
계층형 구조
- REST 서버는 다중 계층으로 구성될 수 있으며 보안, 로드 밸런싱, 암호화 계층을 추가해 구조 상의 유연성을 둘 수 있고 PROXY, 게이트웨이 같은 네트워크 기반의 중간 매체를 사용할 수 있음.

3. REST API 설계 원칙

① URI는 정보의 리소스를 표현해야 한다.

// REST를 제대로 적용하지 않은 URI 예시
GET /members/delete/1

행위에 대한 표현이 아닌 리소스 표현하는데 중점을 두어야 한다.
리소스명은 동사보다는 명사를 사용한다.

② 리소스에 대한 행위는 HTTP Method로 표현한다.

GET, POST, PUT, DELETE 등

// REST 적용 예시 1
GET /members/delete/1 (X)
DELETE /members/1 (O)

// REST 적용 예시 2
GET /members/show/1 (X)
GET /members/1 (O)

// REST 적용 예시 3
GET /members/insert/3 (X)
POST /members/3 (O)

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

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

⑤ 하이픈(-)은 URI 가독성을 높이는데 사용할 수 있다.

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

⑥ 언더바(_)는 URI에 사용하지 않는다.

보기 어렵거나 밑줄 때문에 문자가 가려지는 가독성 문제가 발생한다. 대신 하이픈을 사용한다.

⑦ URI 경로에는 소문자를 사용한다.

대소문자에 따라 다른 리소스로 인식하기 때문이다.
RFC3986(URI 문법 형식)은 URI 스키마와 호스트를 제외하고는 대소문자를 구별하도록 규정하고 있다.

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

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

// REST 적용 예시
http://restapi.example.com/members/soccer/345/pthoto.jpg (X)
GET /members/soccer/345/photo HTTP/1.1 (O)
	Host: restapi.example.com
	Accept: image/jpg

⑨ 단수보다는 복수를 사용한다.

4. HTTP Method

GET
- 리소스를 조회한다.
- 서버에 전달하고 싶은 데이터는 qeury(쿼리 파라미터, 쿼리 스트링)를 통해서 전달한다.
- 메시지 바디를 사용해서 데이터를 전달할 수 있지만, 지원하지 않는 곳이 많아서 권장되지 않는다.
POST
- 새 리소스를 생성할 때 사용한다.
- 메시지 바디를 통해 서버로 요청 데이터를 전달하고 처리하는데 사용한다.
- 단순히 데이터를 생성하거나 변경하는 것을 넘어서 프로세스를 처리해야 하는 경우가 해당한다.
- POST의 결과로 항상 새로운 리소스가 생성되는 것은 아니다.
- JSON으로 조회 데이터를 넘겨야 하는데 GET 메서드를 사용하기 어려운 경우 등, 다른 메서드로 처리하기 애매한 경우 사용한다.
PUT
- 리소스를 대체한다.
- 리소스가 없는 경우 생성한다.
- 클라이언트가 리소스 위치를 알고 URI를 지정하는 점이 POST와의 차이점이다.
- PATCH와의 차이점은, 리소스를 일부만 변경하는 경우에도 바뀌지 않는 속성을 모두 보내야 한다는 점이다.
PATCH
- 리소스를 부분적으로 변경한다.
- PUT과 달리, 변경할 값만 보내면 된다.
DELETE
- 리소스를 삭제한다.
HEAD
- GET과 동일하지만 메시지 부분을 제외하고, 상태 줄과 헤더만 반환한다.
OPTIONS
- 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명한다.
- 주로 CORS에서 사용한다.
CONNECT
- Client가 Proxy를 통해서 Server와 SSL통신을 하고자 할 때 사용된다.
TRACE
- 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트(요청 리소스가 수신되는 경로 확인을 위한)를 수행한다.

5. HTTP 응답 상태 코드

1xx(Informational): 요청이 수신되어 처리 중이다. 거의 사용하지 않는다.
2xx(Successful): 요청이 정상 처리되었다.
3xx(Redirection): 요청을 완료하려면 추가 행동이 필요하다.
4xx(Client Error): 클라이언트 오류, 잘못된 문법 등으로 서버가 요청을 수행할 수 없다.
5xx(Server Error): 서버 오류, 서버가 정상 요청을 처리하지 못한다.

Redirection이란?

업로드중..

종류
- 영구 리다이렉션
  - 특정 리소스의 URI가 영구적으로 이동한다.
  - 원래의 URL을 사용하지 않는다.
  - 검색 엔진 등에서도 변경을 인지한다.
  - 301, 308이 해당한다.
- 일시 리다이렉션
  - 리소스의 URI가 일시적으로 변경된다.
  - 검색 엔진 등에서 URL을 변경하면 안된다.
  - 주문 완료 후 주문 내역 화면으로 이동하는 것이 대표적인 예시이다.
  - 302, 303, 307이 해당한다.
  - 303, 307 사용이 권장되지만 현실적으로는 302가 가장 많이 사용되고 있다.