URL의 Collection, Element

📚 REST API 란?

• RESTful 한 API
• 일련 특징, 규칙 지키는 API 지칭

⚖️ SOAP 와 비교

SOAP	REST
복잡	단순
많은 규칙	적은 규칙
어려움	쉬움

⭐️ 특징

1. Uniform-Interface

• 왜 필요할까?

  • 독립적 진화
    • 서버, 클라이언트가 독립적으로 진화
    • 서버 기능 변경 ←X→ 클라 기능 변경
    • 독립적 인터페이스
    • REST 시작 계기가 웹을 쪼개기 위함

• 어떻게 uniform-interface를 만족할 수 있을까?

  URL 자원식별

  • Identication Of Resources

  • 자원은 url 로 식별 가능해야함

    표현을 통한 자원조작

  • manipulation of resources through representations

  • 자원에 대한 작업에 대해 상태를 설명할 수 있는 정보 포함해야함.

    Self-Descriptive messages

  • 메시지(자원)은 스스로 표현할 수 있어야 함

    • 메시지만 보고도 어떤 작업을 할 것인지 알 수 있어야 함

  • HTTP 헤더에 타입 명시

  • HTTP 헤더에 도메인 명시

  • 각 메시지(자원)는 MIME 타입에 맞춰 표현해야함.

    • .json 반환 → 헤더에 application/json 명시 필요
    • MIME 타입
      • 문서/파일의 특성/형식 나타내는 표준
      • font/ttf, text/plain, text/csv, etc

  • 거의 대부분의 REST 호소인들이 지키지 못한다고 함

    // Self-Descriptive 하지 않은 응답
    HTTP/1.1 200 OK
    [{"op":"remove", "path":"/a/b/c"}]
    
    // Self-Descriptive 한 응답
    // 메시지 내용으로 모든 응답을 수신측이 이해가능
    HTTP/1.1 200 OK
    Host: www.example.org
    Content-Type: application/json.patch+json
    [{"op":"remove", "path":"/a/b/c"}]

    HATEOS 구조

  • Hypermedia as the Engine of Application State

  • 자원에 대해서 할 수 있는 행위를 명시해줘야 한다는 관점

  • 하이퍼링크에 따라 다른 페이지를 보여줘야 함.

  • 데이터마다 어떤 URL 에서 원했는지 명시해야함.

  • 보통 href, links, link, url 속성 중 하나에 해당 데이터의 URL 담아서 표기

  • 거의 대부분의 REST 호소인들이 지키지 못한다고 함

  • 아래 그림 처럼 하이퍼링크를 통한 상태 전이가 있는 경우 REST

    

    HTTP/1.1 200 OK
    Content-Type: application/json
    Link: </articles/1>; rel="previous",
    			</articles/3>; rel="next";
    {
    	"title": "The second article",
    	"content": "어쩌구 저쩌구"
    }

2. Stateless

• HTTP 자체가 Stateless 므로, HTTP 이용만으로 만족하는 특징
• REST API 제공 서버는 세션을 해당 서버에 유지하지 않는다는 의미
• 세션 기반 로그인 같은 경우에는 REST 하지 않은 것
  • 토큰 기반 로그인은 상태가 없으므로 REST 한 것

3. Cachable

• HTTP 는 원래 캐싱 가능
  • 로직 구현 안 했어도 자동적으로 캐싱됨.
  • 새로고침하면 304 응답 나오면서 원래 있던 JS, CSS 이미지 불러오는거가 캐싱
• HTTP GET 메소드 한정
  • Cache-Control:max-age=초단위
    • 캐싱 시간 지정
  • Last-modified
    • 캐싱 데이터 유효성 판단
  • Etag
    • 전달되는 값에 태그 붙여 캐싱되는 자원인지 확인

4. Client-Server 구조

• 클라이언트 / 서버 가 서로 독립
  • 서버는 API 제공 + API 에 맞는 비즈니스 로직 처리
  • 클라는 HTTP 로 받는 로직만 처리
• HTTP 사용으로 가능한 구조

5. Layered System

• 계층구조 아키텍처
• 웹 기반 서비스는 보통 계층구조 아키텍처임

6. Code-On-Demand (optional)

• 서버에서 클라로 코드를 보내서 실행할 수 있어야 함

🔨 REST API 규칙

URL 규칙

• 행위 포함하면 안 됨
  • 행위는 그냥 HTTP 메소드를 사용하는 것으로만 사용해야함
  • 컨트롤 자원 의미하는 url은 예외적으로 동사 허용
• 확장자는 표시하면 안 됨
• 동사 말고 명사로만 표현
• 계층적 내용 포함
  • /집/아파트/전세
• 소문자로만 작성
• _(언더바)말고 그냥 -(대시) 사용
• 마지막에 / 포함 금지

HTTP 헤더 규칙

• Content-Location 속성으로 새로 생성된 리소스 식별할 수 있도록 uri 넣어줌
  • GET, PUT 과 다르게, POST 는 멱등하지 않기 때문에 사용
  • HATEOAS 로 대체 가능
• Content-Type
  • application/json 권장
  • self-descriptive 만족위해 사용
• Retry-After
  • API 비정상접근의 경우 429 (Too many Requests) 응답과 함께 일정 시간 뒤 요청하도록 제어
• Link
  • 페이징 처리에 사용
  • HATEOAS, self-descriptive 만족 위해서도 사용

HTTP 메소드 규칙

• POST, GET, PUT, DELETE 4개 메소드는 반드시 제공할 것
• OPTIONS, HEAD, PATCH 사용해서 완성도 높은 API 만들것
  • HEAD
    • 요청에 대한 헤더 정보만 응답 (바디 없음)
  • OPTIONS
    • 현재 엔드포인트가 제공 가능한 API 메소드 응답
    • Allow: GET, PUT, DELETE, OPTIONS, HEAD

HTTP 상태 규칙

• 의미에 맞는 HTTP 상태를 적재적소에 반환할 것
• HTTP 상태 코드를 응답 객체에 중복으로 표시하지 말것
• 성공은 2XX, 실패는 4XX 으로
• 5XX 은 절대 사용자에게 나타내지 말 것

그외

• 쿼리스트링과 혼합해서 URL 작성
  • 검색, 페이지네이션, 정렬 등 매개변수가 많거나 복잡할 때 쿼리스트링 사용하면 편-안
• 버저닝 사용

  • /api/v1/…

  • 마이그레이션을 편하게 하기 위함.

  • 개발 당시에는 버전 별로 패키지를 나누지 말고, VCS 사용해 관리할 것

    로이필딩 : “버저닝 하지마”

• HATEOAS 사용할 것
• 페이지네이션 사용할 것
• 정렬 사용할 수 있으면 사용할 것
  • 오름차순 : key
  • 내림차순: -key
• 필터링 사용할 수 있으면 사용할 것

🧨 왜 REST 가 잘 안 될까?

• 예제
  • HTML은 REST O
    • Self-Descriptive 만족
    • HATEOAS 만족
  • JSON은 REST X
    • Self-Descriptive 만족
    • HATEOAS 만족

	흔한 웹 페이지	HTTP API
Protocol	HTTP	HTTP
커뮤니케이션	사람 ↔ 기계	기계 ↔ 기계
Media Type	HTML	JSON

	HTML	JSON
Hyperlink	가능 (a 태그)	정의 없음
Self-descriptive	가능 (HTML 명세)	불완전 문법 해석은 가능 의미 해석위해선 API 문서 필요

JSON 의 Self-descriptive 만족시키기

방법1 : Media type

1. 미디어 타입 새로 정의
2. 미디어 타입 문서 작성
   1. 각 변수의 의미 정의
3. IANA에 미디어 타입 등록 + 명세 등록
4. 모든 사람이 해당 미디어 타입 명세에 접근 가능하므로, 메시지 의미 온전히 해석 가능

방법2: Profile

1. 각 변수 의미 정의 명세 작성
2. Link 헤더에 profile relation 으로 해당 명세 링크
3. 메시지 보는 사람은 명세 찾아갈 수 있으므로 의미 해석 가능

JSON 의 HATEOS 만족시키기

• 방법 1 + 2 둘 다 사용하는걸 권장

방법1: data 로

• data 에 다양한 방법으로 하이퍼링크 표현
• JSON 하이퍼링크 표현 방법 정의한 명세 활용
• 기존 API 수정할 부분이 많아짐

방법2: HTTP 헤더로

• Link, Location 헤더로 링크 표현