[HTTP | HTTP 웹 기본지식 | HTTP 메서드 활용] HTTP API 설계 예시

• 이미지, 정적 텍스트 문서

• 조회는 GET 사용

• 정적 데이터는 일반적으로 쿼리 파라미터 없이 리소스 경로로 단순하게 조회 가능

• 주로 검색, 게시판 목록에서 정렬 필터(검색어)

• 조회 조건을 줄여주는 필터, 조회 결과를 정렬하는 정렬 조건에 주로 사용

• 조회는 GET 사용

• GET은 쿼리 파라미터 사용해서 데이터를 전달

• HTML Form submit시 POST 전송

• 예) 회원 가입, 상품 주문, 데이터 변경

• Content-Type: application/x-www-form-urlencoded 사용

• form의 내용을 메시지 바디를 통해서 전송(key=value, 쿼리 파라미터 형식)

• 전송 데이터를 url encoding 처리

• 예) abc김 -> abc%EA%B9%80

• HTML Form은 GET 전송도 가능

• Content-Type: multipart/form-data

• 파일 업로드 같은 바이너리 데이터 전송시 사용

• 다른 종류의 여러 파일과 폼의 내용 함께 전송 가능(그래서 이름이 multipart)

• 참고: HTML Form 전송은 GET, POST만 지원

• 서버 to 서버

• 백엔드 시스템 통신

• 앱 클라이언트

• 아이폰, 안드로이드

• 웹 클라이언트

• HTML에서 Form 전송 대신 자바 스크립트를 통한 통신에 사용(AJAX)

• 예) React, VueJs 같은 웹 클라이언트와 API 통신

• POST, PUT, PATCH: 메시지 바디를 통해 데이터 전송

• GET: 조회, 쿼리 파라미터로 데이터 전달

• Content-Type: application/json을 주로 사용 (사실상 표준)

• TEXT, XML, JSON 등등

 

HTTP API 설계 예시

• HTTP API - 컬렉션

   POST 기반 등록

  예) 회원 관리 API 제공

• HTTP API - 스토어

   PUT 기반 등록

   예) 정적 컨텐츠 관리, 원격 파일 관리

• HTML FORM 사용

   웹 페이지 회원 관리

   GET, POST만 지원

 

 

 

 

URI 설계는 웹 API를 구성하는 중요한 부분이며, 리소스를 명확하게 식별하고 조직화하는 데 도움이 된다. 일반적으로 문서, 컬렉션, 스토어, 컨트롤러로 나누어서 URI를 설계하는데, 이들 각각의 역할에 대해 설명하겠다.

1. 문서(Document)
   • 문서는 개별 엔티티나 객체를 나타내며, 보통 단수 명사를 사용하여 표현된다. 각 문서는 고유한 URI를 가지며, 특정 리소스를 직접적으로 참조한다.
   • 예시: /users/12345
   • 여기서 /users/12345는 ID가 12345인 사용자를 나타내는 문서 리소스를 지칭한다.
2. 컬렉션(Collection)
   • 컬렉션은 동일한 유형의 여러 문서를 그룹화한 것을 말한다. 컬렉션은 복수 명사를 사용하여 표현되며, 특정 유형의 모든 리소스 또는 리소스의 부분집합을 나타낸다.
   • 예시: /users
   • /users는 사용자들의 집합을 나타내며, 이 URI를 통해 사용자 리스트를 조회할 수 있다.
3. 스토어(Store)
   • 스토어는 서버에 저장된 리소스 집합으로 클라이언트가 관리할 수 있다. 컬렉션과 비슷하지만, 클라이언트가 리소스를 생성하고 관리할 때 사용된다.
   • 예시: /files
   • /files URI를 통해 파일들을 관리하며, 파일을 업로드하거나 삭제하는 등의 작업을 수행할 수 있다.
4. 컨트롤러(Controller)
   • 컨트롤러는 리소스에 대한 특정 작업을 수행하는 엔드포인트를 의미한다. 이는 리소스의 상태를 변경하거나 특정 프로세스를 실행하는 데 사용된다.
   • 예시: /users/12345/activate
   • 여기서 /users/12345/activate는 ID가 12345인 사용자의 계정을 활성화하는 작업을 수행하는 컨트롤러 리소스다.

이러한 각 카테고리는 API의 일관성과 이해도를 높이는 데 기여하며, 사용자가 예상 가능한 패턴으로 리소스에 접근할 수 있도록 도와준다. 이렇게 잘 구조화된 URI는 API 문서를 보다 명확하게 만들고, 개발자가 API를 쉽게 사용할 수 있게 해준다.

 

POST와 PUT

POST와 PUT HTTP 메소드는 웹 리소스를 다룰 때 각기 다른 목적과 기능을 가지고 있으며, 리소스의 URI를 결정하는 주체도 이들 메소드에 따라 달라질 수 있다. 아래에서는 이러한 차이점을 포함하여 두 메소드를 자세히 설명하겠다.

1. POST
   • 용도: POST 메소드는 주로 새 리소스를 생성할 때 사용된다. 서버에 데이터를 제출하며, 그 결과로 새로운 리소스가 생성될 수 있다.
   • 멱등성: POST는 멱등성이 없다. 같은 POST 요청을 여러 번 보내면 동일한 데이터로 여러 개의 리소스가 생성될 수 있다.
   • URI 결정: POST 요청에서는 클라이언트가 리소스의 정확한 URI를 지정하지 않는다. 대신, 서버가 새로 생성된 리소스에 대한 URI를 결정하고 할당한다. 예를 들어, /users에 POST 요청을 보내면, 서버는 새 사용자 리소스를 생성하고, 이에 대한 새 URI를 반환한다 (예: /users/123).
2. PUT
   • 용도: PUT 메소드는 기존 리소스를 대체하거나 존재하지 않을 경우 새 리소스를 생성하는 데 사용된다.
   • 멱등성: PUT은 멱등성을 가지며, 동일한 PUT 요청을 여러 번 수행해도 서버의 상태에 동일한 결과를 남긴다.
   • URI 결정: PUT 요청에서는 클라이언트가 리소스의 URI를 명시적으로 지정한다. 이는 클라이언트가 리소스의 위치를 정확히 알고 있고, 해당 위치에 데이터를 저장하거나 업데이트하려 할 때 사용된다. 예를 들어, /users/123에 PUT 요청을 보내면, 클라이언트는 이 URI에 해당하는 리소스를 대체하거나 생성할 의도를 가지고 있다.

차이점 요약

• 용도: POST는 새 리소스 생성, PUT은 리소스 업데이트 또는 생성.
• 멱등성: POST는 비멱등, PUT은 멱등.
• URI 결정: POST에서는 서버가 새 리소스의 URI 결정, PUT에서는 클라이언트가 리소스의 URI 지정.