RESTful API?

katsukichi·2021년 3월 28일
CODESTATESTIL
0

CodeStates_IM

목록 보기
34/48

RESTful API

REST? 그게뭐죠?

백엔드 모집공고에 자주 등장한다.

  • REpresentational State Transfer
    직역 : 표현상태 전달

뭘 표현하고 어떤상태를? 어떻게전달해 ?

  • 웹서비스를 만드는데 사용되는 제약(constraint)모음

  • Roy T.Fielding (라는사람이 박사과정 논문에썻다)
    "web을 망가뜨리지않고, 어떻게 HTTP를 개선할수있을까?"

HTTP와 API

리소스마다 서로 다른 API규칙이라면 그때그때 공부하고 적용하는데에 문제가있엇다.

어떤 조건을 따르면서 API를 만들어보자! (비슷한 스타일)

6가지 Constraints

  • client-server
    클라이언트는 서버와 무관하게 작성되어있어야한다. 서로 독립적이여야한다.
  • stateless
    맥락이없다. 하나의 요청에 이 요청을 처리하기위한 모든정보가 있어야한다. 내가누군지 서버는기억못한다.
  • cacheable
    특정정보들을 미리 서버에 저장할수 있게 해야한다.
  • uniform interface
    같은 스타일의 API와 관련이있다. 동일한 인터페이스로 만들어져있어서 쉽게 알수있어야한다.
  • layered system
    클라이언트와 서버가 1개씩만 있다면 서버가 어떤방식으로 구성되어있고 어떻게동작하는지 몰라도된다.
  • code on demand
    자바스크립트같은 실행할수있는 코드를 내려줄수있어야한다.

HTTP : Client-Server , Stateless, Cacheable, Layered system
HTTP를 써서 잘 작성만 하면 별 힘들이지않고 지킬수 있는것이다.

JavaScript : Code on demand(optional)
옵셔널이고 자바스크립트를 써서 내려주기만하면 OK

집중해야할부분은 Uniform interface이다.

Resource : 자원

"The key abstraction of information in REST is a resource. Any information that can be named can be a resource. - Roy Fielding"

직역 : REST에서 정보의 가장 핵심적인 추상화는 리소스다.
이름붙일수 있는 정보면 어떤것이든 리소스가 될 수 있다.

서버가 뭔가 정보를 내려주면 그것은 리소스

그걸 어떻게 표현하고 그걸 어떻게 조작할것인가.

Uniform Interface

  • Identification of resources
    리소스를 각각 식별할수 있어야한다.
  • manipulation of resources through representation
    리소스를 표현(보내는것)에 의해서 조작할수 있어야한다.
  • self-descriptive messages
    정보를 조작을하기위해서 보내는 메세지에는 거기에 필요한 모든정보가 들어있어야한다.
  • Hypermedia As The Engine Of Application State (HATEOAS)
    한마디로 링크가 있어야한다. (인터페이스를 내려줘서 줬는데 거기에 다음 리소스를 찾는방법을 제공해야한다, 그런 링크들을) -> 추상적이다.너무 추상적이다.

Best Practices

  1. 리소스를 나타내는 데 명사(nouns)를 사용하라

  2. 일관성이 핵심!

  3. CRUD기능 이름은 URI에 사용하지 마라

  4. filter가 필요하면 query componenet를 사용하라

1. 리소스를 나타내는 데 명사를 사용하라

리소스의 가이드라인에서는 4가지정도로 분류한다.

  1. document
		/device-management/managed-devices/{device-id} // 디바이스에 접근한다. 각각의
		/user-management/users/{id} // 개인 유저 1명의 정보
		/user-management/users/admin
  • 쉽게 정리하면 단수? 즉 한명 한명 , 하나 하나의 문서를 의미한다.
  1. collection
		/device-management/managed-devices // 디바이스정보들
		/user-management/users //사용자 정보들
		/user-management/users/{id}/accounts
  • 폴더같은느낌 어떤것을 담고있는,
  1. store
		/cart-management/users/{id}/carts
		/song-management/users/{id}/playlists
  • 여러 컨텐츠, 여러 리소스를 담고있는 - 컬렉션과 유사한 개념이긴한데
  • 차이점은 : 컬렉션은 그룹같은느낌이고 , store는 임시적으로 넣어놓는 공간
  1. controller
		/cart-management/users/{id}/cart/checkout
		/song-management/users/{id}/playlist/play
  • 동작을 취해야한다. -> 동사형
  • 공통적인것은 다 명사형이다.

2. 일관성이 핵심

  1. 계층구조를 나타낼 때는 /를 사용하라
  2. URI 끝에 /를 붙이지 마라
  3. URI의 가독성을 높이기 위해 -를 사용하라
  4. _를 사용하지마라
  5. URI에 소문자를 사용하라
  6. 파일 확장자를 사용하지 마라

3. CRUD기능 이름은 URI에 사용하지마라

CRUD (Create,Read, Update, and Delete):
POST , GET, PUT, DELETE

HTTP GET /device-management/managed-devices
HTTP POST /device-management/managed-devices
HTTP GET /device-management/managed-devices/{id}
HTTP PUT /device-management/managed-devices/{id}
HTTP DELETE /device-management/managed-devices/{id}

별도의 문서없이 API만으로도 충분히 기능을 유추할 수 있다.!

4. filter가 필요하면 query component를 사용하라

/managed-devices
/managed-devices?region=USA
/managed-devices?region=USA&brand=XYZ
/managed-devices?region=USA&brand=XYZ&sort=installation-date

RESTful한 API는 매우 엄격하다.

위 4가지를 지키면 어느정도는 레스트풀하다고 할수있다.

참고자료

  • restfulapi.net
  • "그런 REST API로 괜찮은가" - Naver DEVIEW 2017
  • 가능하다면...? Roy Fielding의 박사학위 논문 (누군가 요약한 내용을봐볼까?)
profile
katsukichi
front-back / end developer / Let's be an adaptable person
이전 포스트

React

다음 포스트

business logic

0개의 댓글