Intro

이번 포스팅의 주제는 RESTful API 디자인 방법이다.
RESTful 한 API를 설계하기 위해서 알아야 할 지침들에 대해 정리 해 보도록 하겠다.

Remind

RESTful API 라는 개념은 많은 주니어 웹 개발자들이 알다가도 모를 수 있는 주제라고 생각한다.
'그래서 RESTful 하다는 게 무슨 의미인가요?' 라는 질문을 들었을 때 필자는 정말 간단하게 '데이터를 전달할 수 있는 HTTP 프로토콜 메소드를 사용하는 API' 라고 답 한 적이 있다.
물론 틀린 말은 아니다. 하지만 그게 명확한 정답이라고 스스로 자신 할 수는 없었다.

우선 RESTful API를 간단하게 설명한다면 웹의 장점을 활용한 네트워크 기반의 API 라고 설명할 수 있다. 기존의 HTTP Method 를 그대로 사용할 수 있다. 그리고 웹에 존재하는 모든 자원들에 고유한 URL을 부여해 활용할 수 있다.

REST 아키텍쳐 스타일을 준수해야 하며 간단히 정리하면 아래와 같다.

• 인터페이스 일관성
• 무상태 (Stateless)
• 계층화
• 캐시 가능성
• 온디맨드 코드
  • 지난 글에서 설명이 부족했던 부분인데 보충하자면 서버는 소프트웨어 프로그래밍 코드를 클라이언트에 전송하여 클라이언트의 기능을 일시적으로 확장하거나 사용자 지정을 할 수 있다는 의미.

REST API 디자인 가이드

• URL 에는 kebab-case

[GET] /businessLogic (X)
[GET] /business_logic (X)
[GET] /business-logic (O)

• Path Variable 에는 camelCase

[GET] /orders/orderId

• Collection에는 단수가 아닌 복수
  • 의미를 명확하게 하는 게 중요하다.

[GET] /users
[GET] /chickens

• Collectoin 으로 시작하여 Identifier로 끝내기

[GET] /shop/{shopId}/category/{categoryId}/price (X) 
[GET] /shops/{shipId} (O)
[GET] /category/{categoryId} (O)

가능하면 각각의 콜렉션 별 데이터 로 URL이 끝나는 게 좋다.

• 동사보다 명사

[GET] /getUser/{userId} (X)
[GET] /user/{userId} (O)

• Non-Resource URL에는 동사

[POST] /send/1234/comfirm

• 가급적 소문자
• HTTP 메소드로 표현
  • GET, POST, PUT, PATCH, DELETE 등
  • CRUD 중 어떤 동작이 진행되는 지 알 수 있어야 함.

[GET] /getProduct/shpps/2/products/21

• 적절한 상태값을 응답해야 함.
  • HTTP 상태코드 기반

  HTTP/1.1 400 Bad Request
  {
      "msg" : "user not found",
      "code" : -200
  }

• JSON property에는 카멜 케이스 사용

{
    productName : "product",
    shopName : "CoffeeShop"
}

• URL 에 파일 확장자 포함 X
  • 대신 Accept Header를 활용함

[GET] /product/thumbnail
Accept : image/jpg

• 버전 구분을 위해 서수 사용

https://api.server.com/v2/product/1234

• list 리소스의 경우 갯수도 함께 응답해야 함.ㅏ

{
    data : [
        ...
    ].
    total : 54
}

• 리스트 응답의 경우 파라미터로 Limit과 Offset 정보를 받아야 한다.
  • 다수의 정보를 조회하는 경우 몇 개의 데이터를 전달 받을 지 미리 Front-end에서 알아야 할 필요가 있다.

[GET] /products?offset=5&limit=5

• 쿼리 파라미터를 위한 매개변수를 가져와야 한다.

[GET] /products?fields=id,name

• 인증 토큰 URL 노출 금지
  • Request Header 에 작성하는 것이 좋음
• URL의 마지막 문자로 슬래시를 포함하지 말 것
  • 리소스가 디렉토리라는 의미
• 리소스 이름에 테이블 명을 그대로 쓰는 것 금지
  • 아키텍쳐 정보 노출은 보안 상 위험이 있을 수 있음.

Outro

간단하게 RESTful API를 작성하는 데 도움이 될 법한 정보들에 대해 기록 해 보았다. 다음 포스팅은 Authentication에 대해 작성 해 보도록 하겠다.