HTTP API 설계 예시

HTTP API - collection

• 위 사진처럼 GET에 뭐 정렬조건, 검색조건 등 파라미터를 넣어서 처리하도록 설계하면 된다..
• 이 memebers의 리소스에 대한 HTTP method의 모음을 collection이라 한다.

신규 자원 등록 특징(POST)

1. 클라이언트는 등록될 리소스의 URI를 모른다.
2. 서버가 새로 등록된 리소스 URI를 생성해준다.
3. Collection은 서버가 관리하는 리소스 디렉토리이다.
   • 서버가 리소스의 URI를 생성하고 관리한다.

신규 자원 등록 특징(PUT)

1. 클라이언트는 등록될 리소스의 URI를 알고있어야한다.
   • 파일 등록 /files/{filename} -> PUT
   • 이렇게 해야 특정 위치의 파일이 없다면 생성을 있다면 갈아엎어줄 수 있다.
2. 클라이언트가 직접 리소스 URI를 지정한다.
3. Store는 클라이언트가 관리하는 리소스 저장소이다.
   • 클라이언트가 리소스의 URI를 알고 관리한다.
   • 여기서 스토어는 /files가 된다.

• 문서(Document)
  • 단밀 개념(파일 하나, 객체 인스턴스, 데이터 베이스 row)
• 컬렉션(Collection)
  • 서버가 관리하는 리소스 디렉토리
  • 서버가 리소스의 URI를 생성하고 관리
• 스토어(Store)
  • 클라이언트가 관리하는 자원 저장소
  • 클라이언트가 리소스의 URI를 알고 관리
• 컨트롤러(Controller), 컬트롤 URI
  • 문서, 컬렉션, 스토어로 해결하기 어려운 추가 프로세스 실행
  • 동사를 직접 사용

상태코드

1xx (Information)

• 요청이 수신되어 처리중
• 거의 사용하지 않음.

2xx (Successful)

• 요청 정상 처리
• 200: OK
• 201: Created
  • 리소스 생성 주로 POST로 생성
  • 이때 응답 message에 신규 리소스 URI의 Location이 함께 들어온다.
• 202: Accepted
  • 요청이 접수되었으나 처리가 완료되지 않은 상태의 응답 코드
  • 배치 처리 같은 곳에서 사용한다.
  • 예) 요청 접수 후 1시간 뒤에 배치 프로세스가 요청을 처리한다.
• 204: No Content
  • 서버가 요청을 성공적으로 수행했지만, 응답 페이로드 본문에 보낼 데이터가 없음.
  • 예) 웹 문서 편집기에서 save 버튼
  • save 버튼의 결과로 아무 내용이 없어도 된다.
  • save 버튼을 눌러도 같은 화면을 유지해야한다.
  • 결과 내용이 없어도 204 메시지(2xx)만으로 성공을 인식할 수 있다.

3xx (Redirection)

• 요청을 완료하려면 유저 에이전트의 추가 행동이 필요

• 웹 브라우저는 3xx 응답의 결과에 Location Header가 있다면, Location 위치로 redirect한다.

• 300: Multiple Choices

• 301: Moved Permenently
  

  • 영구 리다이렉션(거의 대부분의 영구 리다이렉션이 이렇게 되어있음.)
    • 원래의 URL을 사용하지 않고, 검색 엔진 등에서도 변경 인지
  • 라다이렉트 요청 메서드가 GET으로 변하고, 본문이 제거될 수 있음.

• 302: Found

  • 일시 리다이렉션

    • 리소스의 URI가 일시적으로 변경
    • 따라서 검색 엔진 등에서 URL을 변경하면 안됨
    • 주문 완료 후 주문 내역 화면으로 이동
    • PRG: Post/Redriect/Get
      • 새로고침은 마지막 요청을 새로고침하기 때문에 POST가 새로고침되면 POST가 2번 간다. 이런 불상사를 막기위해

  • 리다이렉트시 요청 메서드가 GET으로 변할 수 있고, 본문이 제거될 수 있음

  • 3xx번대 중 가장 많이 쓰임

• 303: See Other

  • 일시 리다이렉션
  • 리다이렉트가 요청 메서드가 "무조건" GET으로 변경하고 조회를 다시 시킴

• 304: Not Modified

  • 특수 리다이렉션
    • 결과 대신 캐시를 사용하는 리다이렉션
    • 클라이언트에게 리소스가 수정되지 않았음을 알려준다.
      따라서 클라이언트는 로컬 pc에 저장된 캐시를 재사용한다. (캐시로 리다이렉트한다.)
    • 304 응답은 응답에 메시지 바디를 포함하면 안된다. 왜냐하면 로컬 캐시를 사용해야 하기 때문이다.
    • 조건부 GET, HEAD 요청시 사용한다.

• 307: Temporary Redirect

  • 일시 리다이렉션
  • 리다이렉트 요청시 요청 메서드와 본문 유지(요청 메서드를 변경하면 "안된다".)

• 308: Permanent Redirect
  
  • 영구 리다이렉션(거의 사용하지 않음. 왜냐면 페이지가 바뀌면 내부 파라미터들도 바뀔 수 있으니까 )
  • 301과 기능은 같음
  • 리다이렉트 요청 메서드와 본문 유지 (처음 POST를 보내면 리다이렉트도 POST를 보내도 내부 html 바디에 보낸 데이터를 유지한다)

4xx (Client Error)

• 클라이언트 오류, 잘못된 문법등으로 서버가 요청을 수행할 수 없음

• 오류의 원인이 클라이언트에 있음

• 클라이언트가 이미 잘못된 요청, 데이터를 보내고 있기 때문에, 똑같은 요청의 재시도가 실패함.

• 400: bad reqeust

  • 요청 구문, 메시지 등등의 오류
  • 클라이언트는 요청 내용을 다시 검토하고, 보내야함.
  • 요청 파라미터가 잘못되거나, api spec이 맞지 않을 때

• 401: unauthorized

  • 인증되지 않음
  • 401 오류 발생시 응답에 www-Authenticate 헤더와 함게 인증 방법을 설명
  • 인증(Authentication): 본인이 누군지 확인, 로그인 같은거
  • 인가(Authoriztiona): 권한부여(admin권한 처럼 특정 리소스에 접근할 수 있는 권한, 인증이 있어야 인가가 있음.)

• 403: forbidden

  • 주로 인증 작격 증명은 있지만, 접근 권한이 불충분한 경우
  • admin 등급이 아닌 사용자가 어드민 등급의 리소스에 접근하려는 경우.

• 404: not found

  • 요청 리소스가 서버에 없음.
  • 또는 클라이언트가 권한이 부족한 리소스에 접근할 때 해당 리소스를 숨기려고 내보내기도 함

• 405: wrong method

  • HTTP 메서드가 잘 못 되었을 때

5xx (Server Error)

• 서버 오류, 서버가 정상 요청을 처리하지 못함

• 500대 오류는 서버나 DB에 문제가 있을 수 있으므로 클라이언트가 똑같은 요청을 재시도해도 요청이 성공할 가능성이 있다.

• 500: Internal Server Error

  • 서버 내부 문제로 오류 발생
  • 애매하면 500에러 날리면 됨

• 503: Service Unavailable

  • 서버가 일시적인 과부하 또는 예정된 작업으로 잠시 요청을 처리할 수 없음
  • Retry-After 헤더 필드로 얼마뒤에 복구되는지 보낼 수도 있다.

클라이언트에서 응답코드

• 나중에 288, 388, 458 이런식으로 convention하게 쓰이는 응답 코드가 아닌 처음 보는 응답코드여도 당황하지 않고 상위 상태코드(3번째 자리 숫자)를 파악하여 처리하면 된다.

• 개발할 때 각 팀들이 어느정도 내부적으로 응답코드를 정하고 사용하는 것이 좋다.
  너무 많아지면 클라이언트 코드가 그걸 가지고 일일이 메시지를 만들거나 처리하는 것도 일이니까 말이다.