Web APIs 디자인 💩 vs 👍

Web APIs의 기본

대부분 REST의 특징은 http 프로토콜과 표준화된 방식만 잘 따라가면, 알아서 따라오는 이점이 있고, hypermedia 특징은 아키텍처를 작성하기가 어렵고 그렇게 하는 곳은 많지 않다.

web API를 디자인할때는 서버에 있는 특정한 데이터를 클라이언트가 읽거나 만들거나 업데이트하거나 삭제하는 기본적인 동작을 지원해주면 된다. (CRUD)

이를 HTTP 메서드와 비유해보면 아래 그림과 같다

주의할 사항

• API 이름에는 액션(메서드)에 대한 내용은 생략해야한다.
  • GET /posts/getPosts (🚫)
  • GET /posts (✅)
• url 이름과 액션(메서드)가 클리어 해야한다.
  • GET /posts/createPost (GET 메서드지만, 포스팅을 생성함 / 메서드에 대한 정보가 url에 존재)(🚫)
  • POST /posts (✅)
  • PUT /posts/1 (아이디 1번 리소스 업데이트)(✅)
  • DELETE /posts/1 (1번 리소스 삭제)(✅)
• 요청하는 궁극적으로 가져오려고 하는 것은 명확해야한다.
  • GET /posts/1/tags (🚫)
  • GET /tags/?postId=1 (✅)
  • GET /tags/?query=cool (✅)

Youtube 의 API 참고

https://developers.google.com/youtube/v3/docs/videos/list

Youtube API를 확인하면, 모든 사용가능한 Hypermedia 링크가 api 응답에 들어가있지않은 것을 확인할 수 있다. REST 특징 중 Hypermedia 룰을 따르지 않는 것이 일반적이다.

REST API의 원칙을 충실히 따르는 Github API

https://developer.github.com/v3/

사용가능한 모든 url에 대한 정보를 응답값으로 전달해준다. (REST Hypermedia 룰)