API URL 설계와 요청 메서드

DeadWhale·2022년 11월 14일
0

HTTP

목록 보기
3/4
post-thumbnail

좋은 URL 설계란?

  • 가장 중요한 것은 “ 리소스 식별 “

리소스의 의미

  • 회원 기능에서 회원을 등록 , 수정이 리소스가 아니다 회원 자체가 리소스
  • 자원을 캐라 ⇒ 자원이 리소스를 의미한다.

어떻게 식별하는게 좋은가?

  • 등록 , 수정 , 조회 하는 것을 모두 배제
  • 회원이라는 리로스만 식별하면 된다. ⇒ 회원 리소스를 URL에 매핑
  • 리소스 ( member ) 와 행위( 조회,등록,삭제,변경 )를 분리

예시

회원 목록 조회/members
회원 조회/members/{id}
회원 등록/members/{id}
회원 수정/members/{id}
회원 삭제/members/{id}
  • 계층 구조상 상위를 컬렉션으로 보고 복수단어 사용을 권장한다 ( member ⇒ members )
  • 리소스 ( member ) 만 가지고 동작을 구분할 수 가 없다.

HTTP Method

중요 메서드

GET리소스 조회
POST요청 데이터 처리 , 등록 같은 경우 사용
(회원가입 , 게시글 , 댓글)
PUT리소스를 대체 해당 리소스가 없으면 생성
PATCH리소스 부분적으로 변경
DELETE리소스를 삭제.

기타 메서드

| HEAD | GET 과 동일하지만 메세지 부분을 제외하고 ,
상태줄과 헤더만 변환 |
| --- | --- |
| OPTIONS | 대상 리소스에 대한 통신 가능 옵션 (메서드)를 설명
( CORS에서 사용된다. ) |
| CONNECT | 대상 자원으로 식별되는 서버에 대한 터널을 설정 |
| TARCE | TRACE 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트 |

GET , POST

GET

  • 리소스를 조회
  • 서버에 전달할 데이터는 쿼리스트링으로 전달
  • 메세지바디를 사용할 수 있지만 권한하지 않는다.
    • 지원하지 않는 서버가 많다

POST

  • 요청 데이터를 처리
  • 메시지 바디를 통해 서버로 데이터 전달
  • 서버는 요청 데이터를 처리
    • 메시지 바디로 들어온 데이터를 처리하는 모든 기능을 수행
  • 전달된 데이터로 신규 리소스로 등록하거나 , 프로세스 처리에 사용한다
❕ POST는 등록하는데만 쓰는 것이 아니다.

스펙

  • POST메서는 대상 리소스가 리소스의 고유한 의미 체계에 따라 요청에 포함된 표현을 처리하도록 요청합니다

예시

  • HTML 양식에 입력된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공

    • HTML Form 에 입력된 데이터로 회원 가입 주문 등에서 사용
  • 게시판 , 뉴스 그룹 , 메일링 리스트 , 블로그 혹은 기사 그룹에 메시지 게시

    • 댓글 달기 , 게시판 글 쓰기
  • 서버가 아직 식별하지 않은 새로운 리소스 생성

    • 신규 주문 생성
  • 기존 자원에 데이터 추가

    • 문서의 끝에 내용 추가
  • 이 리소스 URL에 POST 요청이 오면 요청 데이터를 어떻게 처리 할 지 리소스마다 따로 정해야한다

  • ⇒ 정해진 것이 없다!

  1. 새 리소스 생성
    1. 새로운 리소스 생성
  2. 요청 데이터 처리
    1. 데이터 처리가 아닌 프로세스를 처리해야하는 경우
    2. 결제완료 ⇒ 배달 시작 ⇒ 배달 완료 같이 값 변경이 아닌 프로세스의 단계가 바뀌는 경우
    3. POST의 결과로 새로운 리소스가 생성되지 않는 경우도 있다.
      1. 이런 경우는 컨트롤 URL이라고 한다.
      2. POST / orders/{ 주문번호 }/start-delivery
  3. 다른 메서드로 처리하기 애매한 경우
    1. 쿼리 스트링 말고 JSON으로 조회 데이터를 넘겨야 하는 경우 GET메서드를 사용하기 어려운 경우

POST는 캐싱할 수 없다.

PUT , PATCH , DELETE

PUT

  • 리소스를 대체

  • 폴더에 파일을 없을 경우 생성 있을 경우에는 대체한다

  • 덮어쓰기 같은 느낌

  • 클라이언트가 리소스를 식별한다. ( URL 지정 )

  • 리소스를 “완전” 대체한다 ( 기존 값에만 있는 데이터도 사라진다 )

  • 수정의 목적으로 사용하는 것이 아니다.

PATCH

  • 리소스의 부분적인 수정을 위해 사용
  • 서버에서 지원안하는 경우로 더러 있다.

DELETE

  • 리소스를 제거

HTTP 메서드 속성

안전 ( Safe )

  • 호출해서 리소스를 변경하지 않는다.
  • 단순 조회 같은 경우 안전하다.
  • 호출에 따른 리소스 변화가 일어나지 않은 것을 Safe하다 한다
  • 리소스에 대해서만 고려 한다.

멱등 ( Idempotent )

  • 동일한 요청이 한번 호출하든 1000번 호출하든 결과가 동일하다.

  • GET : 1번 조회하든 100번 조회하든 결과가 동일하다.

  • PUT : 수정이지만 매번 동일한 내용을 PUT함으로서 동일한 결과가 유지된다.

  • DELETE : 한번 지워지면 그 뒤의 호출도 삭졔된 상태로 유지되기 때문에 멱등하다.

  • POST: 멱등하지 않다. 두번 호출 시 같은 결제가 중복해서 발생할 수 있다.

    • 결제 요청 ⇒ 동일한 요청이여도 매번 새로 발생 할 수 있다.

왜 필요하지?

  • 자동 복구 메커니즘
  • 서버가 TIMEOUT등으로 정상적인 응답을 못했을 때 , 클라이언트가 같은 요청을 다시 해도 되는지 판단할 수 있는 근거.

재요청 중간에 다른 곳에서 리소스가 발생하면?

  • 새로운 리소스 추가된 후 GET 재요청 발생 시 문제 발생
  • 멱등은 외부적인 요인으로 인한 중간에 리소스가 변경되는 것은 고려하지 않는다
  • 주체는 오로지 나의 요청
  • 이런 부분은 멱등하지 않는다 서버에서 체크가 필요하다.

캐시 가능

  • 응답 결과를 캐시에서 사용해도 되나?
  • GET, HEAD , POST , PATCH 캐시 가능 ( 스펙상 )
  • 실제로는 GET , HEAD 정도만 캐시로 사용한다고 한다.
    • 캐시 키가 맞아야 가능한대 POST,PATCH는 메시지바디까지 고려해야 함으로 쉽지 않다.

클라이언트 ⇒ 서버 데이터 전송

쿼리 파라미터를 통한 전송 방식

  • GET
  • 정렬 필터 ( 검색어 ), 페이징 ( 페이지 번호를 계산 )

메시지 바디를 통한 데이터 전송 방식

  • POST , PUT , PATCH
  • 회원가입 , 상품 주문 , 리소스 등록 , 리소스 변경

CASE

정적 데이터 조회

  • 이미지 , 순수 HTML , JS 문서형 자료

동적 데이터 조회

  • 검색 , 게시판 목록에서 정렬(검색)
  • 쿼리파라미터
    • ( 파라미터 X )특정 URI 접근 시 해당 정보 조회
    • ( 파라미터 O ) 해당 URL에 접근 시 파라미터를 활용해 검색의 조건으로 사용
    • 메시지 바디는 비추 ( 미지원 서버가 많다 )

HTML Form을 통한 데이터 전송

  • 가입 , 게시글 등 등록 , 데이터의 변경
  • 저장
    • submit 버튼을 누르게 되면 브라우저가 form태그를 읽어 메시지 바디로 구현해 준다.
      • 쿼리 파라미터와 유사한 형태로 HTTP Body에 넣어준다
      • GET이라고 명령하면 쿼리 파라미터로 구현해준다.
        • ( Get은 조회용으로만 SAVE 로직 같은 곳에서는 X)
    • application/x-www.form.urlencoded 사용 시
      • 인코딩 후 전달한다 (UTF-8)같은
    • 파일 자료형 전송 : mulitpart/form-data
      • input type으로 구분된다 file일 경우 경계를 짤라내어 파일과 다른 자료형들을 구분해 전달한다
      • 멀티 파트 == 여러개의 파트 라는걸 이해하기
      • Binary Data Transfer에 사용한다.
  • GET / POST 만 지원

HTTP API를 통한 데이터 전송

  • 회원가입 , 상품 주문 , 데이터 변경
  • 서버 ⇒ 서버
    • 백엔드 시스템 통신
  • 앱 클라이언트
    • 안드로이드 , 아이폰
  • 웹 클라이언트 (Ajax)
    • 웹 클라이언트 API 통신 (Vue , React )
      • HTML Form 대신 자스를 통한 통신으로 활용 (AJAX)
    • POST , PUT , PATCH : 메시지 바디를 통해 데이터 전송
    • GET 조회 쿼리 파라미터도 데이터 전달
    • ContentType 은 applicaiton/json을 주로 사용한다 ( 표준 느낌 )
      • TEXT. XML , JSON

출처

  • 영한님의 모든 개발자를 위한 HTTP 강의를 기반으로 작성

0개의 댓글