URL 디자인

Action(operation)은 method로, Item(domain)은 URL path로

출처: 드림코딩 강의

• API로 우리는 무엇에 대해 어떤 동작을 할건지를 요청하게 된다.
  • 이중 무엇에 해당하는 what, item은 URL path로,
  • 동작에 해당하는 action, operation은 HTTP request method로 나타내게 된다.
    • 동작에 해당하는 부분은 보통 verb로 나타낼 수 있다. e.g. CRUD
• 예를들어 CRUD동작은 각각 POST, GET, PUT, DELETE 메소드로 나타내고,
• URL은 what만 나타내는 것이 이상적이다.

예시 1

• 나쁜예 GET /posts/getPost

  ⇒ 이미 method가 GET이기 때문에 URL이름에 getPost를 포함할 필요가 없다. 중복된다.

  어떤 동작을 할지는 request method로 명시하면 충분하다.

• 좋은예 GET /posts ⇒ 요게 더 이상적이다.

  • 좋은예 PUT /posts/1
  • 좋은예 DELETE /posts/1

예시 2

• 나쁜예 GET /posts/1/tags

  ⇒ 1이라는게 post의 id인지 tag의 id인지, 그리고 요청의 대상도 post인지 tag인지가 명확하지 않다.

• 좋은예 GET /tags?postId=1

• 좋은예 GET /tags?query=cool

  ⇒ 이런식으로 무엇을 원하는지, 제일 관심 있는 현재 요청의 대상은 앞쪽 path로 명확하게 표시하고, 조건은 query string을 통해 나타내는 것이 바람직하다.

API 명세서 작성하기

• API를 잘 설계한다. (실제 URL 디자인 및 개발)
• API URL 목록을 작성한다.
  • 도메인 별로 묶어서 정리하면 좋다.
• 각 API 설명에 포함할 내용은 다음과 같다.
  • Request method 종류
  • URL path
  • (있다면) parameter 형태 및 사용법
  • 요청 양식 및 필요시 요청 예시
    • request body 포함 내용 등
    • JSON이라면 object structure, property name, type 등
  • 응답 양식 및 필요시 응답 예시
    • response body 포함 내용 등
    • JSON이라면 object structure, property name, type 등
  • 필요시 추가 설명.