HTTP API 설계 예시

DeadWhale·2022년 11월 14일
0

HTTP

목록 보기
2/4
post-thumbnail

신규 자원 등록은 POST 기반

/members

  • GET : 목록
  • POST : 가입

/members/{userId}

  • GET : 특정 회원 조회
  • PATCH , PUT , POST : 회원 정보 수정

리소스를 등록할 식별키를 클라이언트가 URI를 모른다

  • 새로운 리소스를 만들여 식별키를 서버가 제공해준다.
  • 새로 등록할때는 서버에서 요청을 구분해서 처리해준다.

컬렉션 ( Collection )

  • 서버가 관리하는 리소스 디렉토리를 컬렉션이라고 명칭한다.
  • 서버가 리소스의 URI를 생성하고 관리
  • 예시에서 컬렉션은 /members

PUT 기반 등록

파일 관리 시스템

/files

  • GET : 파일 목록
  • POST : 대량의 파일을 등록

/files/{name}

  • GET : 파일 조회

  • PUT : 파일 등록

    • 값이 기존에 있으면 덮어씌기를 수행한다. (대체)
  • DELETE : 파일을 삭제

  • 리소스 등록시 클라이언트가 리소스의 URI를 알고 있어야한다.

  • 클라이언트가 직접 리소스의 URI를 지정해주었다.

  • 원래 POST 등록 시에는 식별하지 않고 처리했다.

  • POST : 이 정도 등록해줘~

  • PUT : 이거 덮어써줘~

스토어 ( Store )

  • 클라이언트가 관리하는 리소스 저장소
  • 클라이언트가 리소스의 URI를 알고 관리한다.
  • 예시에서는 /files

HTML FORM

  • 순수 HTML은 GET , POST만 지원
  • AJAX를 사용할 수 있긴하다.

컨트롤 URI

  • 제약이 있다 ( GET, POST)
  • 리소스 경로를 이용해 pathValue으로 컨트롤한다
  • /delete , /update , /edit

정리

https://restfulapi.net/

  • Document
    • 단일 걔념 (파일하나 , 객체 , DB 1 ROW
  • Collection
    • 서버가 관리하는 리소스 디렉토리
    • 서버가 리소스의 URI을 관리
  • Store
    • 클라이언트가 관리하는 자원 디렉토리
    • 클라이언트가 자원의 URI를 알고 사용한다.
  • Controll , Control URL
    • 스스로 해결하기 어려운 경우에 수행되는 컨트롤 구문
    • 동사를 URI 경로에 집어 넣어 사용

상태 코드

요청 후 반환받는 Response에 포함된 상태 코드

1 X X

  • Information : 요청 수산 후 처리 중ㄴ

2 X X

  • Successful : 요청 정상 처리

3 X X

  • Redirectioin : 추가 동작 후 완료 처리 가능

4 X X

  • Client Error 클라이언트 오류 : 잘못된 문법 , 서버가 처리할 수 없다.

5 X X

  • Server Error 서버 오류 : 서버가 정상적인 처리를 수행할 수 없다

  • 클라이언트는 상위 상태코드로만 해석하면 된다.

2XX Success

  • 200 OK
    • 요청 성공
  • 201 Created
    • 요청 성공 && 새로운 리소스 생성
    • Header의 Location 으로 식별 할 수 있다.
  • 202
    • 요청은 접수 됬지만 처리가 완료되지 않음
    • 서버가 잡았지만 배치, 딜레이등으로 늦게 처리 할 때
  • 204
    • 요청은 성공했지만 반환 받을 데이터가 없다
    • ( 임시저장 같은거 ) 웹 문서 편집기에서 SAVE 같은거

3XX Redireaction

웹 브라우저의 추가적인 작업이 필요

Location Header가 있으면 자동으로 해당 URI로 이동한다.

구 버전 페이지에서 리뉴얼된 페이지로 이동 시켜버릴 때와 같이

종류

  • 영구 리디렉션

    • 특정 리소스의 URI가 영구적으로 이동
    • 301 Moved Permanently
      • 리다이렉트 시 요청 메서드가 GET으로 변하고 본문이 제거 될 가능성 이 있다.
    • 308 Permanent Redierect
      • 301과 기능은 동일
      • 리다이렉트 시 POST , GET 메서드를 유지 하기 위해 사용된다.
      • 추후에 추가된 스펙
  • 일시적 리디렉션

    • 리소스의 URI가 일시적으로 변경된다.
    • 302 - Found: 재 요청시 본문이 제거되고. GET으로 변할 수도 있다.
    • 307 - Temporary Redirect : 302와 기능적으로 동일 , 본문과 , 요청 메서드 타입을 유지한다.
    • 303 - See Other : 302와 기능적으로 동일 요청 , 리다이렉트시 요청 메서드를 GET으로 변경
  • 언제 필요하지?

    • PRG ( POST / Redirect /GET )
      • 주문을 요청할떄는 POST
      • 주문 정보를 새로 고침 하게 되면 중복 주문의 가능성이 있다.
      • Redirect 후 다시 POST으로 전송하지 않도록 GET 요청으로 변환할 수 있다.
      • 서버에서도 방지해야 하지만 클라이언트쪽에서 관리해야 한다.
  • 특수 리디렉션

    • 만료된 캐시 생성을 위한 이동 (결과 대신 캐시를 사용)
    • 300 :안씀
    • 304 Not Modify
      • 캐시를 목적으로 사용한다.
      • 클라이언트에게 리소스 수정이 없었다는걸 알려준다.
        • 클라이언트는 로컬 PC에 저장된 캐시를 읽어 재사용한다.
      • 304 응답 시에는 메시지 바디를 포함하면 안된다. ( 로컬 캐시를 사용해 하기 때문)
      • GET / HEAD 요청 시 사용된다

4XX Client Error

  • 클라이언트의 잘못된 요청
  • 원인의 원인이 클라이언트 쪽에 있다.
  • 클라이언트가 이미 잘못 요청했기 때문에 재시도 시에도 계속 불능하다
    • 5XX 서버 에러는 서버의 에러가 고쳐지면 재시도 시에 가능할 가능성이 있다.

400 Bad Request

  • 요청 오류
  • 파라미터 실수
  • API 스텍이 안맞을 때.
    • 서버개발자들이 500에러가 되기 전 최대한 방지해야 한다.

401 Unauthorized

  • 클라이언트가 접근한 리소스에 대해 인증이 필요함

  • Authentication 되지 않았다.

  • 401 에러 발생 시 응답에 WWW-Authenticate 헤더와 함께 인증 방법을 설명

  • 인증 ( Authentication )

    • 본인이 누구인지 확인 :: 로그인
  • 인가 ( Authorization )

    • 권한 부여 ( ADMIN 과 같은 특수 리소스 접근 권한 )
    • 인증 ⇒ 인가
      • 인증을 우선 받아야 인가를 확인할 수 있다.
      • 일종의 권한 레벨 ( Access Level )
    • 오류가 Unauthorized 이지만 인증되지 않음

404 Not Found

  • 요청한 리소스가 서버에서 찾을 수 없다.
  • 또는 클라이언트가 권한(Authorization)을 가지고 접근하려 할때 리소스를 숨기고 싶어

5XX Server Error

서버 오류

500 Internal Server Error

  • 서버 내부 문제

503 Service Unavailable

  • 서비스 이용 불가
  • 일시적인 과부하
  • 예정된 작업으로 잠시 요청 처리 불가

서버 내부의 에러이기 때문에 정말 심각한 문제일 경우에만 500 응답을 보내야 한다

고객이 예금을 출금 ⇒ 잔고가 부족 ⇒ 500 ERROR

  • 로직상에는 문제가 없기 떄문에 500으로 해결하는건 부적절하다.

출처 / 참고

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

0개의 댓글