Network

Network HTTP(HyperTextTransferProtocal) API 설계

, ,

1. API URI(Uniform Resource Identifier) 설계

1.1. Resource(리소스)란?

API URI설계에서 중요한것은 리소스의 식별입니다.
리소스(Resource)라고 하는것은 단순히 조회하고 수정 등록하는것을 일컫는 말이 아니라 만약 멤버의 정보를 조회한다고 했을때 멤버의 정보를 조회하는것이 리소스가 아니라 멤버라는 자체가 리소스(Resource)라고 할 수 있습니다.

1.2. 리소스 식별 방식

멤버의 조회,생성,수정,삭제의 의미가 아니라 멤버자체만을 리소스로 식별하고 회원 리소스를 URI에 매핑하면 됩니다.

  • 멤버 목록조회
    /members
  • 멤버 개별조회
    /members/{id}
  • 멤버 등록
    /members/{id}
  • 멤버 수정
    /members/{id}
  • 멤버 삭제
    /members/{id}

해당 5개의 API가 있다고 가정해보겠습니다. 여기서도 가장 중요한것은 리소스를 식별하는 방식입니다.

URI는 리소스만 식별하고 리소스와 리소스를 대상으로 하는 행위를 분리하여 URI를 설계를 진행합니다.

리소스: 멤버(명사)
행위: 목록조회, 개별조회, 등록, 수정, 삭제(동사)

2. HTTP 메서드

2.1. HTTP Method 종류

  1. GET: 리소스를 조회합니다.
  2. POST: 요청 데이터 처리, 주로 등록에 사용합니다.
  3. PUT: 리소스를 대체하고 리소스가 없다면 생성시킵니다.
  4. PATCH: 리소스를 부분 변경합니다.
  5. DELETE: 리소스를 삭제합니다.

2.2. HTTP 기타 메서드 종류

  1. HEAD: GET과 유사하지만 메시지부분을 제외 하고, 상태 줄과 헤더만 반환합니다.
  2. OPTIONS: 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명합니다. (CORS)
  3. CONNECT: 대상 자원으로 식별되는 서버에 대한 터널을 설정합니다.
  4. TRACE: 대상 리소스에 대한 경로에 따라 메시지 루프백 테스트를 수행합니다.

3. GET 메서드

  1. 리소스를 조회합니다.
  2. 서버에 전달하고 싶은 데이터는 쿼리 파라미터(쿼리스트링)을 통해서 전달됩니다.
  3. 메시지 바디를 사용하여 데이터를 전송할 수 있지만 지원하지 않는곳이 많아 권장하지않는 방식입니다. 최근에는 허용이 되었지만 실무에서는 잘 사용되지 않는 방식입니다.

4. POST 메서드

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

  1. 요청 데이터를 처리합니다.
  2. 메시지 바디를 통하여 서버로 요청 데이터를 전달합니다.
  3. 서버는 요청 데이터를 처리하고 메시지 바디를 통해서 들어온 데이터를 처리하는 모든 기능을 수행합니다.
  4. 주로 전달된 데이터로 신규 리소스 등록, 프로세스 처리에 사용됩니다.

POST가 사용되는 기능

  • HTML양식에 입력된 필드와 같은 데이터 블록을 데이터 처리 프로세스에 제공합니다.
    (회원가입,주문)

  • 게시판, 뉴스 그룹, 메일링 리스트, 블로그 또는 유사한 기사 그릅에 메시지를 게시합니다.
    (글쓰기, 댓글달기)

  • 서버가 아직 식별하지 않은 새 리소스를 생성합니다.
    (신규주문)

  • 기존 자원에 데이터 추가
    (문서에 내용 추가하기)

즉, 이 리소스 URI에 POST요청이 오면 요청 데이터를 어떻게 처리할지 리소스마다 따로 정해야합니다.

POST 정리

  1. 새 리소스를 생성합니다.(등록)
    서버가 아직 식별하지 않은 새 리소스를 생성합니다.

  2. 요청 데이터 처리할때 사용됩니다.
    데이터 생성하거나 변경을 넘어서 프로세스를 변경해야할 경우 POST를 사용합니다.
    결제 -> 주문 -> 완료와 같은 프로세스의 상태가 변경되는 경우에 사용합니다.
    POST의 결과로 새로운 리소스가 생성되지 않는 경우도 있습니다. 컨트롤 URI라고 하며 동사가 포함된것들로 컨트롤되어집니다.

  3. 다른 메서드로 처리가 애매한 경우에 사용됩니다.
    JSON 데이터 형식으로 데이터를 넘길때 GET 메서드를 사용하기 어려운 경우 POST를 사용합니다.

5. PUT 메서드

  1. 리소스를 대체합니다. 대체한다는 의미는 리소스가 있으면 대체하고 리소스가 없으면 리소스를 생성합니다. 즉, 리소스를 덮어버리게 됩니다.

  2. 클라이언트가 리소스를 식별합니다. 클라이언트가 리소스 위치를 알고 URI를 지정합니다.
    (POST와 차이점)

6. PATCH 메서드

  • 리소스를 부분만 교체합니다.

7. DELETE 메서드

  • 리소스를 제거합니다.

8. HTTP 메서드의 속성

  1. 안전(Safe Methods)
    GET같은 경우는 안전하며 POST,PUT과 같은 변경이 많은 것들은 안전하지 않습니다. 호출해도 리소스를 변경하지 않습니다. 안전은 리소스만 고려합니다.

  2. 멱등(Idempotent Methods)
    여러번 호출해도 결과는 같아야합니다. PUT을 호출하여 서버응답 호출을 통하여 재시도 할지 안할지를 확인할 수 있습니다. 즉, 자동 복구 매커니즘에서 많이 활용됩니다.

만약, 재요청 중간에 다른 곳에서 리소스를 변경하게 된다면 멱등성은 외부 요인으로 중간에 리소스가 변경되는것 까지 고려하지 않습니다.

  • 멱등메서드
    GET:여러번 조회하든 결과가 같습니다.
    PUT: 결과를 대체하여 여러번 요청해도 최종 결과는 같습니다.
    DELETE: 결과를 삭제합니다. 같은 요청을 여러번 해도 삭제된 결과는 같습니다.

POST: 멱등성을 가진 메서드가 아닙니다. 두번 호출시 주문 중복이나 결제 중복이 발생할 수 있습니다.

  1. 캐시가능(Cacheable Methods)
  • 응답 결과 리소스를 캐시해서 사용할 수 있습니다. (GET, HEAD, POST, PATCH)
  • GET,HEAD정도만 캐시로 사용하고 POST, PATCH같은 경우는 본문 내용까지 캐싱을 진행해야하기 때문에 주로 GET,HEAD를 사용합니다.

9. 클라이언트 서버 데이터 전달 방식 2가지

  1. 쿼리 파라미터를 통한 데이터 전송
  • GET, 정렬 필터 검색어 처리를 할때 사용됩니다.
  1. 메시지 바디를 통한 데이터 전송
  • POST, PUT, PATCH를 사용하며 리소스 등록이나 리소스 변경에 사용됩니다.

데이터 전달시 상황

  1. 정적 데이터 조회
    이미지, 정적 텍스트 문서

  2. 동적 데이터 조회
    주로 검색이나 게시판 목록에서 정렬필터에 사용됩니다(검색어)

  3. HTML Form을 통한 데이터 전송
    회원 가입이나 상품주문, 데이터 변경이 발생하는곳에 사용됩니다.

  4. HTTP API를 통한 데이터 전송
    회원 가입이나 상품주문 데이터변경시에 사용되고 서버간 통신이나, 클라이언트, 웹클라이언트 통신에 주로 사용됩니다. (Ajax, axios)

10. 정적 데이터 조회시

  1. 이미지나 정적 텍스트 문서에 사용됩니다.
  2. 조회는 주로 GET을 사용합니다.
  3. 정적 데이터는 일반적으로 쿼리 파라미터 없이 리소스 경로로 단순하게 조회 가능합니다.

11. 동적 데이터 조회

쿼리 파라미터를 기반으로 정렬필터를 통하여 결과를 동적으로 생성하는 경우가 있습니다.

  1. 검색, 목록에서 정렬 필터 및 검색어 등에 사용됩니다.
  2. 조회 조건을 줄여주는 필터나 조회 결과를 정렬하는 정렬 조건에 주로 사용됩니다.
  3. 조회는 주로 GET을 사용하고 쿼리파라미터를 통하여 데이터를 전달합니다. 메시지바디를 통하여 가능하지만 실무에서는 권장하지 않는 방식입니다.

12. HTML From 데이터

  1. HTML Form Submit시에는 보통 POST전송을 진행합니다.
  • 가입, 주문, 변경
  1. Content-Type: application/x-www-form-urlencoded
  • form의 내용을 메시지 바디를 통하여 전송합니다. (쿼리파라미터)
  • 전송 파라미터를 url encoding 처리합니다.
    kgh -> kgh%A%B%C%D%E%F%
  1. HTML Form GET 전송 가능
  2. Content-Type: multipart/form-data
  • 파일 업로드 같은 바이너리 데이터 전송시 사용합니다.
  • 다른 종류의 여러 파일의 폼 내용과 함께 전송이 가능합니다(multipart)
  1. HTML Form전송은 GET,POST만 지원

13. HTTP API 데이터 전송

  1. 서버간 통신
  • 백엔드 시스템 통신(OPEN API)
  1. 앱 클라이언트
  • IOS, Android
  1. 웹 클라이언트
  • HTML에서 Form전송 대신 자바스크립트 통신(axios, ajax)
  1. 메시지 바디를 통하여 메시지 전송
  • POST,PUT,PATCH를 주로 사용합니다.
  1. GET: 조회, 쿼리파라미터로 데이터전달
  • Content-Type: application/json 주로 사용
  • TEXT, XML, JSON

14. HTTP API 설계

  1. HTTP API 컬렉션
  • POST 기반 등록 및 회원관리 API
  1. HTTP API 스토어
  • PUT 기반등록으로 진행되고 정적 컨텐츠나 원격 파일 관리에 사용됩니다.
  1. HTML FORM
  • 웹 페이지 회원 관리에 사용되며 GET,POST Method만 지원됩니다.

15. 멤버 관리 시스템 예시

POST기반 멤버 관리 시스템

목록 /members :GET
등록 /members :POST
조회 /members/{id} :GET
수정 /members/{id} : PATCH, PUT,POST
리소스 덮는게 가능하면 PUT, 부분 교체하면 PATCH, 그외 POST
삭제 /members/{id} : DELETE

POST 신규 자원 등록의 특징

  1. 클라이언트는 등록될 리소스의 URI의 정보를 모릅니다.
  • POST /members
  1. 서버가 새로 등록된 리소스 URI를 생성해줍니다.
  • HTTP/1.1 201 Created
  • Location: /membmer/1
  1. 컬렉션(Collection)
  • 서버가 관리하는 리소스 디렉토리이며 리소스의 URI를 생성하고 관리합니다.
  • 컬렉션 예: /members

16. 파일 관리 시스템 예시

PUT 기반 등록 시스템

목록 GET /files
조회 GET /files/{filename}
등록 PUT /files/{filename}
삭제 DELETE /files/{filename}
대량 등록 POST /files

PUT 신규 자원 등록

  1. 클라이언트가 리소스 URI를 알고 있어야합니다.
  • 등록 PUT /files/{filename}
  • PUT /files/hello.jpg
  1. 클라이언트가 직접 리소스의 URI를 지정합니다.
  2. 스토어(Store)
  • 클라이언트가 관리하는 리소스 저장소이며 리소스의 URI를 알고 관리합니다.
  • 스토어 예: /files

17. HTML FORM 사용시 설계

목록 GET /members
등록 폼 GET /members/new
등록 POST /members/new(보통 등록폼과 맞추어준다), /members
조회 GET /members/{id}
수정 폼 GET /members/{id}/edit
수정 POST /members/{id}/edit, /members/{id}
삭제 /members/{id}/delete

특징

  1. HTML FORM GET, POST만 지원
  2. 컨트롤 URI
    GET,POST 제약조건을 가지고 있으며 이러한 제약을 해결하기 위해 동사로 된 리소스 경로를 사용합니다. POST /new, /edit, /delete가 컨트롤 URI로 사용되며 HTTP메서드로 해결하기 애매한 경우 사용됩니다. (HTTP API를 포함합니다)

HTTP 설계 정리

  1. HTTP API 컬렉션(서버)
    POST기반으로 등록되며 서버가 리소스 URI를 결정합니다.

  2. HTTP API 스토어(클라)
    PUT기반 등록되며 클라이언트가 리소스 URI를 결정합니다.

  3. HTML FORM
    순수 HTML + HTML form을 사용하며 GET, POST만 지원합니다.

Share