REST API 개념 정리

아데스티·2023년 1월 31일

개념 정리 시리즈

목록 보기
3/4

REST API 개요

API란? Application Programming Interface
소프트웨어와 소프트웨어 사이 데이터 전송을 가능하게 하는 프로그램입니다.

API중에서도 웹의 장점을 잘 살린 아키텍쳐입니다.
이해하기 쉽고 활용도 높은 REST API 기법을 사용해 유저와 팀원은 API를 더 빠르게 이해하고 활용할 수 있게 됩니다.
간단하게 협업시 가독성을 높이기 위한 네이밍 패턴이라고 봐도 무방합니다.

기본 전제 : Uniform-Interface

자원들이 각각의 독립적인 인터페이스를 가져야 합니다.

  • 서비스 이용중 새로운 버전이 나왔어도 전 버전은 유지가 되어야 합니다.
  • 웹페이지를 변경한다고 해서,
    • 기존 버전 서비스를 즉시 중단하고 웹 브라우저가 업데이트 되는 일은 없어야 합니다.
  • 이를 다르게 표현하면 아래와 같습니다.
    • HTTP명세나 HTML 명세가 변경되어도 웹페이지는 잘 작동해야합니다.

REST API의 6가지 특징

  1. Self-descriptive messages
  2. Stateless
  3. Cacheable
  4. Client-Server 구조
  5. Layered System
  6. HATEOAS 구조

이 중 Stateless Client-Server Layered System HATEOAS 구조를 집중해서 보겠습니다.

Stateless

일반적으로 HTTP는 Stateless (무상태성)입니다.
로그인을 했는 데, 로그인을 한 상태를 유지하지 못합니다.
상태를 기억하기 위해서 쿠키와 토큰 또는 세션을 활용합니다.
하지만 REST API는 Stateless를 전제로 깔고 있으므로
구축한 서버에서 세션을 두지 않는 것을 원칙으로 하고 있습니다.

Client-Server

클라이언트와 서버가 서로 독립적인 구조를 가져야 합니다.
이러한 구조는 HTTP를 썼을 때 가능한 구조입니다.
서버에서 HTTP 표준만 지켜도 그에 따른 화면이 잘 나타납니다.

  • 서버는 API만 제공하고, 그 API에 맞는 비즈니스 로직들을 처리해줍니다.
  • 클라이언트에서는 HTTP로 받아오는 로직만 잘 처리하면 됩니다.

Layered System

계층구조를 이루는 아키텍처로 만들어야 합니다
공통적인 특징을 파악하고 단계별 성숙도를 이해해보도록 하겠습니다.

  1. 명사를 사용합니다. 동사를 사용하지 않습니다.
    1. 유저가 책을 소유한다
    2. 유저/유저 ID/inclusion/책/책 ID
  1. 동작은 메서드로 정의합니다.
    1. PUT DELETE POST GET
    2. 이를 HTTP를 통한 인터랙션(상호작용)이라고 합니다.
  1. URI는 계층적인 내용을 담고 있어야 합니다
    1. /집 /아파트 /전세
    2. 컬렉션 : Movies (복수) / Inception (DB 내 고유 식별자)
    3. /Movies/inception
  1. 명사 + HTTP 메서드 로 작성을 합니다.
    1. 같은 URL 다른 메서드
      • GET /movies
        • POST / movies
    2. DELTE 나 UPDATE 의 경우
      1. 보통 고유 식별자를 사용합니다.
      2. URL을 바꿀 필요 없이 식별자만 추가하면 됩니다.
  1. 필터를 처리하는경우
    1. 안좋은 URI
      1. /getTopRatedMovies
      2. /findMovieFromThisYear
    2. query parameters를 활용
      1. 매 검색마다 URL을 새로 만들지 않아도 돼서 좋습니다
      2. /movies?min_rating=9.8
      3. /movies?release_date=2021
      4. /movies?page=5
  1. 기타 특징
    1. 표기법
      1. 확장자를 표기하지 않습니다
      2. 소문자를 사용합니다
      3. 이름이 길면 하이픈-을 사용합니다.
      4. 언더바_를 사용하지 않습니다.
    2. HTTP 응답 상태코드를 활용합니다.

도서관 시스템 REST API

app.get(’/books/’)모든 책을 조회합니다
app.post(’/books/booksid’)책을 생성합니다
app.put(’/books/booksid’)책을 수정합니다
app.get(’/books/booksid’)특정 책을 조회합니다
app.put(’/users/userid/books/booksid’)어떤 유저가 특정 책을 빌립니다
app.patch(’/users/userid/books/booksid’)어떤 유저가 특정 책을 빌립니다

HATEOAS 구조

  1. 각 하이퍼링크에 대응하는 다른 페이지를 보여줘야 합니다.
  2. 모든 데이터는 어떤 URL의 호출을 받은 건지 명시해주어야 합니다
    → 데이터 + Link 프로퍼티

REST 성숙도 모델

로이 필딩이 논문에서 제시한 REST 방법론을 바탕으로
보다 더 실용적으로 적용하기 위해 레오나르드 리차드슨(Leonard Richardson) 이 발표한
REST 성숙도 모델을 구조화한 그림입니다.

각 단계별 핵심은 아래와 같습니다.

0단계: HTTP로 불러들이기
1단계: 엔드 포인트를 추가한 URI + 성공 실패에 따른 결과 정보
2단계: 적절한 HTTP 메서드
3단계: HATEOAS ( 링크를 넣어 효율적인 관리와 가독성 )

0단계

단순히 HTTP 프로토콜을 사용하기만 합니다
- 아직, REST API라고 할 수 없습니다.

예시

  • 주치의: 허준
  • 예약 가능한 시간을 확인
  • 특정 시간에 예약하는 상황
  • 단순히 HTTP 프로토콜을 사용하는 REST API의 시작 상태

1단계

REST API는 웹에서 사용되는 모든 데이터나 자원(Resource)을 HTTP URI로 표현합니다

1단계의 핵심: 엔드포인트

  • 개별 리소스(Resource)와의 통신을 준수합니다
  • 요청하고 받는 자원에 대한 정보를 응답으로 전달합니다
    • 요청 : 예약 가능한 시간 확인
    • 응답 : 허준이라는 의사의 예약 가능한 시간대
  • 모든 자원은 개별 리소스에 맞는 엔드포인트(Endpoint)를 사용합니다
    • 0단계 : /appointment
    • 1단계 : 요청하는 리소스에 따라 다른 엔드포인트
      • 예) /doctors/허준

엔드 포인트 지칭 및 작성 법

특정 시간 예약을 시도(POST)하면
[ 예약 가능한 시간 확인 ]이 가지고 있는 요청 시간대에 해당하는 값이 추가됩니다.

  • { slots 리소스 내부의 id }에 해당하는 리소스

[ 특정 시간에 예약 ]이라는 요청에서는
실제 변경되는 리소스를 엔드포인트로 사용해야 합니다.

  • /slots/123 : { slots 리소스 내부 id : 123 }

엔드 포인트는 다음과 같은 상황에 맞춰 다르게 주어야 합니다.

  • 변하는 리소스 대상
  • 응답의 종류

이때 동사는 사용하지 않습니다.

  • 리소스에 집중 (명사)

성공 / 실패에 따른 응답

응답메시지는 사용한 리소스에 대한 정보와 성공/실패 여부를 함께 반환해야 합니다.
김코딩 환자가 허준 의사에게 9시에 예약을 진행하였으나

  • 해당 시간이 마감되어 예약이 불가능하다고 가정
  • 리소스 사용에 대한 실패 여부를 포함한 응답

2단계

2단계의 핵심: HTTP 메서드

CRUD에 맞게 적절한 HTTP 메서드를 사용해야 합니다.

  • 0단계, 1단계에서는 HTTP 메서드를 구분하지 않았습니다.
  • 모든 요청에 POST 메서드를 사용했습니다.

케이스별 CRUD 구분이 필요합니다.

  • 예약 가능한 시간을 조회(READ)
  • 해당 특정 시간에 예약을 생성(CREATE)

CRUD 에 대응하는 URI 작성

  • 조회(READ) : GET
    • GET 메서드는 body를 가지지 않습니다.
    • 필요한 리소스를 전달하기 위해
      • 추가로 query parameter를 사용합니다.
  • 예약을 생성(CREATE): POST
    • POST 메서드 요청의 응답 메시지에 성공여부와 실패여부가 작성되어 있습니다.
  • 리소스 생성에 성공 : 201 Created
    • 새롭게 생성된 리소스를 보여줍니다.
  • 클라이언트가 URI 확인 가능
    • Location 헤더에 작성된 URI가 작성되어 있어야 합니다.

HTTP 메서드

HTTP 메서드 규칙

  • GET : 서버의 데이터를 변화시키지 않는 요청에 사용합니다.
  • POST : 요청마다 새로운 리소스를 생성합니다.
  • PUT : 요청마다 같은 리소스를 반환합니다.

HTTP 요청 메서드

멱등(idempotent)

  • 매 요청마다 같은 리소스를 반환하는 특징입니다.
  • 동일한 요청을 한 번 보내는 것과 여러 번 연속으로 보내는 것이
    • 같은 효과를 지니고, 서버의 상태도 동일하게 남을 때,
    • 해당 HTTP 메서드가 멱등성을 가졌다고 말합니다.
    • 모든 안전한 메서드는 멱등성도 가집니다.
  • 멱등성 : GET, HEAD, PUT, DELETE
  • 멱등성❌ : POST
  • PUT PATCH 구분
    • PUT : 교체,
    • PATCH : 수정

GET /pageX HTTP/1.1는 멱등성을 가집니다.

  • 여러 번 연속해서 호출해도 클라이언트가 받는 응답은 동일합니다.
	GET /pageX HTTP/1.1
    GET /pageX HTTP/1.1
    GET /pageX HTTP/1.1
    GET /pageX HTTP/1.1

POST /add_row HTTP/1.1는 멱등성을 갖지 않습니다.

  • 여러 번 호출할 경우, 여러 열을 추가합니다.
	POST /add_row HTTP/1.1
    POST /add_row HTTP/1.1   -> Adds a 2nd row
    POST /add_row HTTP/1.1   -> Adds a 3rd row

DELETE /idX/delete HTTP/1.1의 상태 코드는 응답마다 달라질 수 있지만,

  • 그럼에도 멱등성을 가집니다.
	DELETE /idX/delete HTTP/1.1   -> Returns 200 if idX exists
    DELETE /idX/delete HTTP/1.1   -> Returns 404 as it just got deleted
    DELETE /idX/delete HTTP/1.1   -> Returns 404

3단계

HATEOAS(Hypermedia As The Engine Of Application State) : 하이퍼미디어 컨트롤

  • 요청 : 2단계와 동일합니다.
  • 응답 : 리소스의 URI를 포함한 링크 요소를 삽입합니다.

3단계의 핵심: 링크

응답 내에 링크 프로퍼티를 추가해 새로운 기능에 접근할 수 있도록 합니다

  • 예약을 할 수 있는 링크를 삽입
  • 확인할 수 있도록 링크를 작성
  • 하이퍼링크에 따라 다른 페이지를 보여줘야 합니다.
  • 데이터마다 어떤 URL에서 원했는 지 명시해주어야 합니다

참고 링크

REST API
자세히 알아보는 REST API | API - 큰돌의 터전
5분만에 제대로 설계하는 ⭐️ REST API - 노마드 코더

HTTP Method
HTTP 요청 메서드 - MDN
HTTP METHOD
A Quick Overview of HTTP Methods

멱등성 - MDN

profile
아데스티
종착지이자 거점 A Destination
이전 포스트

API AJAX CSR&SSR 개념 정리

다음 포스트

React 개념정리

0개의 댓글