HTTP API

주형(Jureamer)·2022년 1월 20일

HTTP API 작성법

1. URI를 작성할 때 '리소스'를 파악해야한다.

'유저 조회' /read-user
'유저 등록' /regist-user
'유저 수정' /update-user
'유저 삭제' /delete-user
예를 들어 위와 같이 4개의 API가 존재한다면 '리소스'는 '유저(user)'가 된다.

2. 메소드는 '행위'를 가르킨다.
조회, 등록, 수정, 삭제와 같은 동사들을 GET, POST, PUT, PATCH, DELETE 등의 메소드로 변형 할 수 있다.

주로 사용되는 메소드
- GET - 단순 조회나 필터를 이용한 조회에 주로 이용된다.
- POST - 주로 등록에 사용되지만 이외에도 다양한 쓰임새로 사용될 수 있다.
- PUT - 값을 대체할 때 사용되며, 기존 값에 덮어쓰기 때문에 사용에 주의가 필요하다.
- PATCH - 값을 일부 교체할 때 사용된다.
- DELETE - 이름 그대로 값을 삭제할 때 사용됨.
기타 메소드
- HEAD - GET에서 응답바디를 제외하고 상태 줄과 헤더만 반환하는 형태
- OPTIONS - 대상 리소스에 대한 통신 가능 옵션(메서드)을 설명(주로 CORS에서 사용)
- CONNECT - 대상 자원으로 식별되는 서버에 대한 터널을 설정
- TRACE - 대상 리소스에 대한 경로를 따라 메시지 루프백 테스트를 수행

3. 컨트롤 URI
간혹 리소스와 메소드만으로 URI를 작성할 수 없을 때, 동사의 형태로 등록해야 할 경우가 있는데, 이를 컨트롤 URI라고 부른다

http://api.example.com/cart-management/users/{id}/cart/**checkout**
http://api.example.com/song-management/users/{id}/playlist/**play**
위의 checkout과 play가 컨트롤 URI에 해당

메소드의 특성

- 안전(Safe) : 기존 값에 영향을 주지 않는 것
- 멱등성(Idempotent): 여러 번 요청해도 결과값은 한 번 요청한 이후로 변하지 않는 것. 이는 자원 복구 등의 장점이 있다.
ex) DELETE /user/1
DELETE /user/1 --> 이미 삭제 되었기 때문에 재삭제가 불가능

그리고 재요청 중간에 다른 곳에서 리소스를 변경해버리는 등의 경우는 고려하지 않는다.
ex) GET /user/1
PUT /user/1
GET /user/1

- 캐시가능(Cacheable) 응답결과를 서버에 캐시해서 사용되는 경우로, 실무에서는 GET정도만 사용하며, 다른 메소드는 구현하기 까다로워 잘 사용되지 않는다.

클라이언트에서 서버로 데이터 전송

데이터 전달 방식은 크게 2가지

1. 쿼리 파라미터를 통한 데이터 전송

GET(주로 정렬필터가 해당)

2. 메시지 바디를 통한 데이터 전송

POST, PUT, PATCH(회원가입, 상품 주문, 리소스 등록, 리소스 변경 등)

클라이언트->서버로 데이터를 전달하는 4가지 상황

1. 정적데이터조회
텍스트, 이미지 파일 등을 정적으로 조회할 경우 리소스 경로만으로 처리가 가능하며 GET을 사용한다.
2. 동적데이터조회
쿼리파라미터를 사용한 동적 데이터 조회. 주로 필터 등을 이용한 조회에 사용 되며 GET을 사용한다.
3. HTML Form 데이터 전송
(한 번도 사용 해보지 못한 전송법) HTML 소스만으로 전송이 가능하며, 아래와 같이 action과 method 등을 정의하여 사용가능하다. 단, GET, POST만 사용 가능

<form action="/user" method="get">
  <input name="username">
  <input name="age">
  <button type="submit">

Content-type default는 x-www-form-urlencoded
쿼리 파라미터 처럼 key, value 형태로 만들어서 body 에 만들어준다.
전송 데이터를 url encoding 처리해준다.

파일도 전송하고 싶다면 form 태그 안에 enctype="multipart/form-data" 속성으로 사용 가능하다.

4. HTTP API 데이터 전송
서버 to 서버 백엔드 시스템 통신, 앱 클라이언트, 웹 클라이언트(Ajax)에서 사용하며, Content-type은 application/json을 주로 사용

HTTP API 설계 예시

1. POST 기반 등록 예시

• 회원 목록 /members -> GET
• 회원 등록 /members -> POST
• 회원 조회 /members/{id} -> GET 
• 회원 수정 /members/{id} -> PATCH, PUT, POST
• 회원 삭제 /members/{id} -> DELETE

- 클라이언트는 등록될 리소스의 URI를 모른다.

ex) 회원등록/members -> POST

- 서버가 새로 등록된 리소스 URI를 생성해준다.

HTTP/1.1 201 Created
Location: /members/100

- 컬렉션(Collection)

서버가 관리하는 리소스 디렉토리
서버가 리소스의 URI를 생성하고 관리
여기서 컬렉션은 /members

2. PUT 기반 등록 예시(파일 관리 시스템)**

• 파일 목록 /files -> GET
• 파일 조회 /files/{filename} -> GET
• 파일 등록 /files/{filename} -> PUT
• 파일 삭제 /files/{filename} -> DELETE
• 파일 대량 등록 /files -> POST

-> 아마 우리 프로젝트에서 이미지 등록 부분은 PUT으로 대체해야할 듯함
- 클라이언트가 리소스 URI를 알고있어야함

파일등록 /files/{filename} -> PUT
PUT /files/start.jpg

- 클라이언트가 직접 리소스의 URI를 지정한다.
- 스토어(Store)

클라이언트가 관리하는 리소스 저장소
클라이언트가 리소스의 URI를 알고 관리
여기서 스토어는 /files

3. HTML FORM 사용**

• 회원 목록 /members -> GET
• 회원 등록 폼 /members/new -> GET
• 회원 등록 /members/new, /members -> POST
 * 등록 폼 -> 등록으로 가는 URI(/new까지)는 대체로 맞춰주는 편이 좋다(리다이렉션 등을 고려해서)

• 회원 조회 /members/{id} -> GET
• 회원 수정 폼 /members/{id}/edit -> GET
• 회원 수정 /members/{id}/edit, /members/{id} -> POST
• 회원 삭제 /members/{id}/delete(컨트롤 URI) -> POST

HTML FORM은 GET, POST만 지원
다른 메서드를 사용하기 위해 AJAX 같은 기술을 사용해서 해결
컨트롤 URI
• 문서 , 컬렉션, 스토어로 해결하기 어려운 추가 프로세스를 실행한다.
문서, 컬렉션, 스토어가 뭔지 헷갈린다면 다시 스크롤을 올려 찾아보자.
• GET, POST만 지원하므로 제약이 있음
• 이런 제약을 해결하기 위해 동사로 된 리소스 경로 사용
• POST의 /new, /edit, /delete가 컨트롤 URI
• HTTP 메서드로 해결하기 애매한 경우 사용(HTTP API 포함)