REST API

REST API란 무엇이고 어떻게 사용하나?

API란 무엇인가?

API(Application Programming Interface)란 어플리케이션 끼리 연결을 하기 위한 약속이다. API를 작성하는 것은 웹 앱에서 원하는 기능을 수행하는 URL과 인터페이스를 만드는 것이다. API를 만들면 클라이언트가 원하는 행위를 처리해줄 수 있다. 예를 들어, 클라이언트가 보낸 데이터를 DB에 저장하거나 저장한 데이터를 읽고 클라이언트에게 보내주는 등 말이다.

REST란 무엇인가?

REST(Representational State Transfer)은 분산 하이퍼아미디어 시스템(예: WWW)를 위한 소프트 아키텍처 형식 중 하나다.

RESTful API의 구성 요소

• Resources(자원) : 주문, 상품, 고객 등 시스템의 특정 객체를 지칭한다.
• URI : API을 통해 특정 자원에 접근하기 위한 통로
• HTTP methods : Verb(행동)을 표현하는데, 표준 HTTP 메소드와 동일(GET, POST, PUT, PATCH, DELETE)
• 요청-응답 데이터 포맷 : JSON을 주로 많이 쓰고, XML, YAML 등도 지원
• 상태코드 : HTTP 상태코드를 사용

REST 아키텍처의 원칙

1. URI 리소스 표현
2. HTTP 메소드로 행동 표현(POST, GET, PUT, PATCH, DELETE)

포맷 : 행동 + 자원

GET /members/delete/1  (X)
DELETE /member/1  (O)

GET /members/show/1  (X)
GET /members/1  (O)

GET /members/insert/2  (X)
POST /members/2  (O)

위 잘못된 예시 모두 URI에서 자원 뿐만 아니라 행동까지 포함했다는 점이다. URI에는 자원만 포함하자.

REST API 가이드라인

Collection, Document

Collection, Document 모두 URI에 표현되는 리소스이다. 컬렉션은 복수로 표현한다.(lookbooks)

룩북 Collection에 SS22시즌의 document를 예시로 들어보자.

http:// restapi.example.com/lookbooks/SS22
http:// restapi.example.com/lookbooks/SS22/product023

리소스 관계 표현

/리소스명/리소스ID/관계 리소스명
GET : /users/{userid}/clothing

복잡한 관계 표현. ex) 특정 유저가 '좋아요' 누른 옷들
GET : /users/{userid}/likes/clothing

Do's and Don'ts

1. 슬래시 `/`는 계층 관계를 표현
https://goodman.com/products/clothing

2. URI의 마지막에 /를 쓰지 않는다
https://goodman.com/products/clothing  (O)
https://goodman.com/products/clothing/ (X)

3. 하이폰(-)은 긴 URI을 쓸 경우 사용
https://goodman.com/products/brother-and-sister (O)

4. 밑줄(_)은 안쓴다
밑줄 대신 하이폰 사용할 것을 권유

5. 대문자 보다는 소문자를
대분자는 다른 리소스로 인식하는 경우 있음

6. 파일 확장자를 URI로 쓰지 않음
https://goodman.com/products/clothing/jacket.jpg  (X)



HTTP 응답 코드

좋은 Rest API는 리소스 뿐만 아니라 응답 코드까지 Restful하다.

200 : 클라이언트 요청 정상 수행
201 : 클라이언트 생성 요청 잘 수행했고, 리소스 잘 생성됨

400 : 클라이언트 요청 부적절하다
401 : 인증되지 않은 클라이언트가 허가가 필요한 리소스를 요청했을 때 거부하는 응답(로그인 안하고 리소스 요청 시)
403 : 인증 상관없이 허가 불가한 리소스 요청했을 경우. 403보다는 400 또는 404이 적절하다. 왜냐하면 403은 리소스가 존재한다는 것을 암묵적으로 인정하는 메시지이기 때문
404 : 해당 리소스에서 사용 불가능한 Method 이용했을 경우

301 : 클라이언트가 요청한 리소스의 URI가 변경되었을 때(응답 시 변경된 URI를 Location header로 줘야함)

500 : 서버에 문제가 발생한 상황

REST API는 언제 탄생했고 어떻게 발전해왔나?

REST API는 2000년도에 Roy Fielding의 박사 논문에 소개되었습니다. Roy Fielding은 HTTP 스펙을 개발한 사람 중 한명인데 HTTP가 이렇게 좋은 기술인데 사람들이 제대로 사용하지 못하는 것을 보고, 이를 잘 사용할 수 있도록 REST 아키텍처를 고안해냅니다. 참고로 REST는 Representational State Transfer의 약자입니다.

RESTful API의 특징


Restful API의 주요 특징 6가지 입니다.

Uniform(유니폼 인터페이스)
Stateless(무상태성)
Cacheable(캐시)
Self-descriptiveness(자체 표현 구조)
Client-Server 구조
계층형 구조

Uniform

URI로 지정한 리소스를 일관된 방식으로 조작합니다.

Stateless

REST는 상태 정보를 저장하지 않습니다. 예를 들어 세션, 쿠키를 따로 저장하지 않아 구현이 단순해집니다.

Cachable

REST는 HTTP의 캐싱 기능을 사용할 수 있습니다. Last-Modified 태그나 E-Tag를 사용하면 됩니다.

Self-descriptive

부가적인 설명 없이 REST API 메시지만으로 통신에 대해 이해할 수 있습니다.

Client-Server 구조

서버는 API를 제공하고, 클라이언트는 인증과 세션 관련 부분을 직접 관리합니다. 각자 할 일이 명확해서 구현 목표가 명확하고 의존성도 줄입니다.

계층형 구조

PROXY, 게이트웨이, 보안 계층, 로드밸런싱, 암호화 계층 추가 등 다중 계층으로 유연하게 구성할 수 있습니다.

REST API를 어떤 산업이나 어플리케이션에서 사용할 수 있을까?

RESTAPI는 다양한 분야에서 사용한다. 이커머스, 헬스케어, 금융, 소셜미디어 등 다양하다.

이커머스의 경우 상품 정보, 장바구니, 유저 계정 등에 사용한다. 헬스케어의 경우 건강 기록, 병원 정보

REST API의 대체 기술?

GraphQL

Facebook이 개발한 쿼리 언어로, 클라이언트가 원하는 정확한 정보를 제공하는 장점이 있다. 구독 방식으로 실시간 업데이트가 가능하다. 복잡한 데이터 구조를 가졌거나 모바일 어플리케이션에 적합한 기술이다.

gRPC

고성능 오픈소스 RPG(Remote Procedure Call) 프레임워크로 구글이 개발했다. 데이터 직렬화를 위해 프로토콜 버퍼를 사용한다. 마이크로서비스들 간 빠른 응답과 높은 처리량을 위해 설계되었다. 대용량 분산 처리 시스템 또는 고성능 어플리케이션에 적합한 기술이다.

SOAP

Simple Object Access Protocol의 약자로 XML을 사용하는데, 옛 기술이다.

JSON-RPC, XML-RPC

클라이언트가 서버의 메소드를 호출할 수 있는 Remote procedure call 프로토콜이다. 각 데이터 방식으로 인코딩한다. 가볍고 간단하지만 보안상 몇몇 단점들이 있다고 한다.

Message Queuing

비동기 통신에 적합한 방식이다. RabbitMQ, Apache Kafka, Amazon SQS 등이 있다. 프로듀서와 컨슈머라는 두 지점을 따로 두고 대용량의 메시지를 처리한다.

프로젝트에서 사용한 예시

경매 시스템 서버 구축을 위한 '스톡 피라미드' 프로젝트의 경매(Raffle) 모듈의 컨트롤러 부분이다.
https://github.com/thursdaycurry/stockpyramid-forked/blob/main/src/raffles/raffles.controller.ts

// raffles/raffles.controllers.ts
...

@Controller('raffles')
...

  // POST /raffles
  @Post()
  create(@Body() createRaffleDto: CreateRaffleDto) {
    this.rafflesService.create(createRaffleDto);
  }

  // GET /raffles
  @Get()
  findAll() {
    try {
      return this.rafflesService.findAll();
    } catch (Error) {
      this.logger.log(Error);
    }
  }

  // GET /raffles/:id
  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id) {
    try {
      return this.rafflesService.findOne(id);
    } catch (Error) {
      this.logger.error(Error);
    }
  }

POST /raffles
POST 메소드와 raffles URI로만 경매(Raffles) 정보를 생성하는 API 임을 알 수 있습니다. URI에는 리소스 정보만 넣어야 한다는 REST API의 원칙을 고려하여 행동과 리소스 정보를 분리했습니다.

GET /raffles/:id
URI를 복수 단위의 컬렉션(raffle -> raffles)으로 표현하여 계층 구조를 강화
Collection, Document 모두 URI에 표현되는 리소스이다. 컬렉션은 복수로 표현한다.(lookbooks)

RESTful APIs 전략

versioning, security, pagination

RESTful API Versioning 전략

버저닝은 어플리케이션의 전체를 바꾸지 않고도 변경사항을 적용할 수 있도록 API를 설계하는 방법을 제시한다.

URI Path로 버저닝

http://www.example.com/api/1/products

수정사항의 범위와 영향력에 따라 MAJOR.MINOR.PATCH 형식으로 세부적으로 관리할 수 있다. 장점은 클라이언트가 특정 리소스(URI)를 캐싱하기가 쉽다. 단점으로는 API의 브랜치가 많아질 수록 코드 복잡도가 증가한다는 점이다.

Query 파라미터로 버저닝

http://www.example/com/api/products?version=1

URI Path 버저닝 방식과 유사하지만 파라미터에 버전을 표시한다는 점에서 차이가 있다. 장점은 명시적으로 표현되어서 알아보기 좋다. 단점은 쿼리 파라미터를 통한 요청을 라우팅하기 까다로울 수 있다.

헤더를 통한 버저닝

curl -H "Accepts-version: 1.0"
http://www.example.com/api/products

헤더를 사용하면 URI에 따로 버전을 기재하지 않아도 된다는 장점이 있다. 단점으로는 헤더를 커스터마이징 해야한다는 수고가 든다.

content negotiation을 통한 버저닝

curl -H “Accept: application/vnd.xm.device+json; version=1” http://www.example.com/api/products

장점은 전체 API가 아니라 특정 버전의 API만 요청하기 때문에 품이 적게 든다. 게다가 URI 라우팅 규칙에 대해 고민하지 않아도 된다. 단점은 브라우저로 미디어 타입의 HTTP 헤더 요청을 테스트하기가 어렵다는 점이다.

What are the potential risks and challenges associated with REST APIS?

performance, security, scalability

Reference

• https://meetup.nhncloud.com/posts/92
• https://www.xmatters.com/blog/blog-four-rest-api-versioning-strategies/