HTTP #6 기본적인 API 설계

# Request (클라이언트 ➡ 서버)

• URI 에 쿼리 파라미터를 통한 데이터 전송 ➡ ✔GET
• HTTP Form을 이용하여 데이터 전송 ➡ ✔POST
• 직접 Body에 데이터를 넣어 전송 ➡ ✔POST, PUT, PACTH

참고로 웹 브라우저에서는 메서드 지정이 없다면 기본값을 GET으로 사용한다.

그래서 웹 브라우저에서 GET요청은 URI 입력으로 바로 가능하지만 POST PUT등은 코드 작성하거나 추가적인 도구를 이용해야 한다. (Postman)

 

 

@ GET - 정적, 동적데이터 조회

• GET을 사용한다. 정적인 데이터는 경로만 지정하면 되니 파라미터가 필요없다.
• 요청 메시지가 필요한 동적인 데이터는 URI (=Header)에 쿼리 파라미터를 넣어 요청한다.

 

 

@ HTML Form을 이용한 전송

HTML에 있는 <form> 태그를 이용하여 전송하게 되면 다음과 같은 동작이 일어난다.

• POST 메서드 Content-type = application/x-www-form-urlencoded 방식으로 헤더를 지정한다.
  ➡ x-www-form은 웹에서 보낸 폼데이터임을, urlencoded는 한글같은 문자를 인코딩해서 Body에 넣었다는 의미.
• 바디에 쿼리 파라미터와 동일한 형식 (username=kim&age=20)으로 데이터를 적어서 전송한다.

 

<form enctype="multipart/form-data">로 인코딩 타입과 content-type을 변경할 수 있다.

이 경우 여러 데이터파일을 하나의 메시지로 인코딩하여 전송한다. (*이는 HTTP 파일 전송에서 따로 다루겠다.)

multipart에는 파일데이터를 part단위로 합쳐서 메시지에 담는 방법이다. 그 중 form-data 타입을 사용한 것.

 

 

@ HTTP API 데이터 전송

클라이언트 스크립트 코드 (예: AJAX 통신 - Asynchronous JavaScript and XML)를 이용한 HTTP 통신 방법이다.

뭐든 전송할 수 있긴하지만, 보통 Content-type: application/json을 표준 메시지 타입으로 사용한다. (이전에는 XML)

서버-서버 간에서도 HTTP API를 많이 이용한다.

 

---

# 요청 HTTP API를 설계해보자

보통 HTTP API를 설계한다고 하면, 크게 3가지 경우로 나눌 수 있다.

만약 서버에서 메서드를 지원하지 않거나 사용하기 애매하다면 POST를 사용하는게 제일 낫다.

 

 

@ URI 설계하기

이전 글에서도 언급했지만, URI로 리소스의 위치를 지정하고 메서드로 동작하도록 설계하는게 좋다.

➡ member/id가 아닌 members/id를 사용한건 멤버 저장소(members)에서 꺼내온다는 의미를 나타내기 위함이다.

HTML-form처럼 쿼리파라미터를 사용해도 되지만, URI의 계층구조를 사용하는게 더 깔끔하다.

 

 

@ POST - 신규 자원등록

• 클라이언트는 등록될 리소스의 URI를 모른다.
  ➡ 회원 등록 /members -> POST
  ➡ POST /members
  
  
• 서버가 새로 등록된 리소스 URI를 생성해준다.
  ➡ HTTP/1.1 201 Created
      Location: /members/100
   
• 컬렉션(Collection)
  ➡ 서버가 관리하는 리소스 디렉토리
  ➡ 서버가 리소스의 URI를 생성하고 관리
  ➡ 여기서 컬렉션은 /members 를 의미한다.

 

@ PUT 기반 등록

• PUT은 클라이언트가 리소스의 위치(id등)를 알고, 정확하게 지정해준다.
• 반면에 POST는 단순히 요청만 하는거지 리소스의 위치는 서버가 지정한다.

파일 등록은 PUT으로 설계하는 것이 적절하다. 새로운 파일이 올라오면 기존 파일을 대체해야 하니까.

➡ 하지만 대부분의 경우는 POST로 처리하게 된다. 굳이 리소스의 위치를 기억해두고 지정할 필요가 없으니까

 

@ HTML Form 만 사용해서 구현 (GET, POST)

그럼 추가적인 JS코드 없이 HTTP Form만을 이용해서 클라이언트 데이터를 받는 서비스는 어떻게 만들어야 할까?

➡ 이 경우 최대한 GET, POST를 활용하고 대체재로 컨트롤 URI( /members/new, delete, edit )을 사용한다.

보통 [폼을 /members/new], [등록과 수정을 /members] 로 사용하는게 깔끔하다. (폼으로 리다이렉션하기 편함) 

물론 HTTP API의 경우에도 upgrade, doService 같이 메서드로 구현하기 애매한 기능은 컨트롤URI 를 사용하기도 한다.

 

---

# 참고하면 좋은 URI 설계 (restfulapi.net)

매번 URI의 이름을 고민하는건 번거로운 일이다. 그래서 사용하기 좋은 설계를 참고해서 만들자.

컬렉션과 문서는 위에서 사용했던 것과 같다.

PUT을 사용하는 저장소를 Store라고 한다. HTTP 메서드로 해결이 안되면 컨트롤URI를 쓰자.