게시판 API 설계 - gesipan API seolgye

API 설계를 구글 문서롤 작성한다. 뷰와 api에 어떤 방식으로 url이름을 지정할 것인지, method 방식은 어떻게 할 것인지, 해당 url의 설명과 함께 문서를 작성한다.

url은 다른 협업 개발자가 봤을 때고 직관적으로 어떤 항목에 관련된 url인지 파악할 수 있게 작성하는 것이 중요, 이에 대한 방법은 왕도가 없으니 협업 개발자들과 합의를 통해 지정해야한다. 지금 작성한 것이 정답은 아님.

지금은 경로와 http 메소드만 작성한 것인데, 여기서 api의 spec을 작성한다. api에 정확히 어떤 데이터들을 주고받는지를 생각해볼 수 있다.

이렇게 사용자가 회원 가입을 할 때, id, 비밀번호,이메일,닉네임,메모와 같은 데이터가 입력된다거나, 사용자가 게시판을 작성할 때, 제목,본문,id,해시태그가 입력된다 같은 방식으로, 사용자가 어떤 작업을 진행할 때, 어떤 데이터가 오고 가는지를 개략적으로 파악하면, 개발진행이 수월해 질수 있다.

이렇게 api 설계는 마무리 되었다.

이번 TIL은 인프런의 "모든 개발자를 위한 HTTP 웹 기본 지식"을 학습하고, 정리한 내용입니다.
만약, 제 글의 내용을 퍼갈 시에는 " 모든 개발자를 위한 HTTP 웹 기본 지식 "도 출처에 첨부하시기 바랍니다.

"리소스"는 복수형으로 쓴다

• 회원 => members
• 파일 => files

API 설계에서 중괄호는??

HTTP API를 어떤 식으로 이 URI를 설계하는지 설계 예시를 살펴보자!!

1. HTTP API - 컬렉션

API 설계 - POST 기반 등록

• POST 기반 등록
  ex) 회원 관리 API 등록

회원 관리 시스템을 설계해야 한다고 가정해보자!!

제일 중요한 것은 URI는 리소스를 식별한다는 것이다.

리소스 : 회원 => members => /members 이걸 "컬렉션"이라고 함

• 회원 목록 조회 => GET

  • 회원 목록들을 JSON으로 내려주면 된다.
  • 하지만, 회원 목록이 100만개이면, 특정 회원을 검색할 수 있는 검색어가 필요하다. 그런 검색어를 쿼리파라미터로 넣도록 설계하자!!
  • 또한, 정렬하고 싶으면, 정렬 조건도 쿼리파라미터에 넣도록 하자!!

• 회원 등록 => POST

  • /members라는 컬렉션에다가 뭔가 데이터를 넣으면, 회원이 새로 등록 되게 할 꺼야. 이렇게 약속을 했다고 하자!!
  • 그렇게해서, /members에다가 회원 데이터를 하나 넣어주면, 회원이 추가로 등록 되도록 만든다.

• 회원 조회 => GET

  • /members라는 컬렉션 아래에다가 조회하고 싶은 id를 넣어주면 되겠다.

• 회원 삭제 => DELETE

  • 삭제하고 싶은 id를 받아서, 지워주면 된다.

• 회원 수정 => PATCH, PUT, POST

  • PATCH는 부분적으로 수정할 수 있다. 그래서, 데이터를 수정할 때는 PATCH로 하는 게 제일 좋다.
  • 그런데, PUT을 쓸 수도 있다. 클라이언트 쪽에서 데이터를 완전히 덮어버려도 문제가 없는 상황이라면 OK!
    ex) 게시판의 글
    => 게시판 글은 전체를 다 수정하기 때문에 덮어버리는 게 맞다.
  • PATCH도 PUT도 애매하다면, POST를 쓰면 된다.

• (중요) POST로 데이터를 등록할 때는 서버에서 보통 리소스 URI를 결정하고 만들어 준다.
  • 그래서, 응답할 때, Location에다가 리소스의 위치를 넘겨준다.
  • 아니면, message body에 "id":100 이런 식으로 위치를 넘겨준다.

2. HTTP API - 스토어

API 설계 - PUT 기반 등록

• PUT 기반 등록
  ex) 정적 컨텐츠 관리, 원격 파일 관리

쉽게 말해서, 구글 클라우드에 내 파일들을 짚어넣고 관리하는 상황이다.

• 파일 목록 조회 => GET

  • 현재 /files에 있는 목록들이 다 나온다.

• 파일 조회 (단일 조회) => GET

  • 특정 파일 하나만 조회하고 싶다면 /files/{파일명}을 받아서 조회할 수있다.

• 파일 등록 => PUT

  • 새로 업로드할 파일명은 클라이언트가 알고 있다. 그래서 {filename}을 받는다.
  • 만약에 없으면, 새로 생성하고!! 있으면, 기존의 것을 대체한다.
  • 파일 업로드 시에, 기존 파일이 있으면, 지우고 다시 올려야 하기 때문에 PUT을 사용하기에 딱 맞는 상황이다.

• 파일 삭제 => DELETE

  • {파일명}을 주면, 그 파일이 삭제

• 파일 대량 등록 => /files => POST

  • 여기서는 PUT 가지고 파일을 등록하고 있기 때문에, POST의 의미를 내가 임의로 정할 수 있다.
  • 여기서는 임의로 대량의 파일 등록이라고 지정했다.

• POST도 데이터를 등록하는데 쓸 수 있고, PUT도 새로운 데이터를 저장하는데 쓸 수 있다.
  • 하지만, 이 2개를 활용할 때, 다른 특징이 있다. 이것을 아는 것이 굉장히 중요하다!!

⚡POST 등록 VS PUT 등록⚡

PUT을 사용할 때 POST와 다른 점은 클라이언트가 직접 리소스의 URI를 지정해준다.
즉, 클라이언트가 생성된 리소스의 URI를 다 알고, 본인이 관리한다는 의미이다.
반면에, POST로 등록할 때는 /members만 넘기고 끝났다. 그리고 리소스의 URI는 서버가 알아서 만들어서 클라이언트 쪽으로 내려준다.

정리하면,
POST로 신규 데이터를 등록한다는 것은 클라이언트가 서버에 요청한다는 의미이다.
PUT 기반의 등록은 PUT 자체가 리소스 URI를 다 알고 등록해야 한다. star.jpg의 위치를 클라이언트가 다 알고, 서버에 그 위치까지 찍어서 보내준다.
이런 스타일의 관리를 스토어(Store)라고 한다!!

그럼 둘 중에 어떤 방식을 더 많이 쓸까??

대부분 POST 기반의 신규 자원 등록방식을 쓴다. 즉, 컬렉션을 거의 다 쓴다.
PUT은 "파일 업로드" 같은 몇몇 케이스 빼고는 거의 사용하지 않는다.
실무에서는 대부분 POST 기반의 방식을 보게 된다.

3. HTML FORM 사용

• 웹 페이지 회원 관리
• GET, POST만 지원
  • 그러나, AJAX같은 기술을 사용해서 해결 가능 => 회원 API 참고
• 여기서는 순수 HTML, HTML FORM 이라는 상황 설정
• 다시 말해서 GET, POST만 지원하므로 제약이 있음

HTML FORM 이니까 기본적으로 HTML이 그려진다고 생각하자!!

• 회원 목록 => GET

  • HTML에 쫙 그려질 것이다.

• 회원 등록 폼 => GET

  • 회원 등록 폼이 렌더링 된다.

• 회원 등록 => POST

  • 회원 등록 폼이 그려지면, 회원 정보를 입력해야 할 것이다. 그리고 submit 버튼을 누르면, POST로 넘어갈 것이다.
  • 이때, 2가지 방식으로 회원 등록을 만들 수있다.
  • /members/new vs /members => POST
  • 그러나, 강사님이 선호하는 스타일은 GET과 POST가 같은 URI를 사용하는 것이다.
    => GET/members/new , POST/members/new
  • 왜냐면, validation !!
  • POST/members/new라 해서 서버에 던졌는데, 서버에서 뭔가 문제가 있어서 다시 그 POST의 최종 결과를 회원 등록 폼 (GET/members/new)에 다시 보내야 하는 경우가 있다. 이렇게 GET과 POST 경로를 맞춰놓으면, 되게 깔끔하게 해결된다.
    그러나, URI가 다르면, URI 경로 자체가 이동해버리기 때문에, 폼을 새로고침했을 때, 다시 회원 등록 폼으로 못 돌아간다.
    => 물론, 개발자들마다 스타일의 문제라서 절대적인 옳고 그름은 없다.

• 회원 조회 => GET

  • 회원 목록이 쭉 나오면, 거기서 하나를 클릭한다. 회원 상세 화면으로 들어가 질 것이다. 그러면, 해당 회원 상세 HTML이 출력된다.

• 회원 수정 폼 => GET

  • 그 회원 상세 화면에서 수정 버튼이 있다면, 수정하기로 이동해야 한다.
  • members/{id}/edit에서 해당 회원 id를 받는다.
  • 그러나, 아직 변경이 일어난 게 아니고, 수정 폼 자체를 보는 것이기 때문에 GET을 쓴다. 변경은 수정 폼을 서버로 보낼 때 일어난다.

• 회원 수정 => POST

  • 이제 변경된 폼에 수정 버튼을 눌렀을 때, 발생한다.
  • 이때, HTML 폼 데이터가 서버로 전송이 되어한다. 그때 URI 경로에 대해서 고민해야 하는데, 이때도 2가지 방식으로 구현 가능하다.
    => POST/members/{id} , POST/members/{id}/edit
  • 강사님이 폼의 URI와 수정 URI를 맞추는 것을 선호한다.
    => GET/members/{id}/edit , POST/members/{id}/edit

• 회원 삭제 => POST

  • DELETE 메서드를 못 사용하기 때문에, 어쩔 수없이 delete라는 컨트롤 URI를 사용해야 한다.
    => POST/members/{id}/delete

HTML FORM은 GET, POST만 지원하기 때문에 제약이 있다. 그래서 컨트롤 URI를 쓸 수밖에 없다.

실무에서는 컨트롤 URI 많이 쓴다.
단, 컨트롤 URI를 남발하면 안 된다. 최대한 리소스라는 개념을 가지고 URI를 설계하고 그 상황에 정말 안 될 때, 컨트롤 URI로 대체한다.

그리고 HTTP API(1번)도 깔끔하게 HTTP 메서드들만으로 다 구현이 안 된다.
그래서, 막상 해보면 컨트롤 URI를 써야 하는 경우가 많다.

참고하면 좋은 URI 설계 개념

자료 출처 : REST Resource Naming Guide

여러 사람들이 API를 설계하다보니까, 좋은 practice들이 보인다. 그게 모이고 모이고 모여서, 결국 사람들이 정리해내고 체계화 시킨 것들이 위의 4가지 개념들이다. 물론, 정답은 아니고 좋은 practice라고 이해하자!!

위 practice들에 대한 자세한 설명은 자료 출처 링크에서 확인하자!!

• 문서는 {id}이런 가변적인 파라미터가 없는 딱 하나의 파일을 말한다.

• 스토어는 파일같은 형식이나 게시판 같은 형식을 쓸 때 사용한다. 그러나, 대부분 경우 컬렉션을 압도적으로 많이 사용한다.

• 컨트롤러(controller) === 컨트롤 URI
  => CRUD만으로는 모든 문제가 절대 해결이 안된다.
  => 그럴 때, 추가적인 프로세스를 위해 어쩔 수없이 사용한다.
  ex) 회원의 주문의 상태를 다음 상태로 진행해...
  => CRUD만으로 굉장히 애매함!!