REST API 사용하기 쉽게 만드는법 정리

[포구디] REST API 사용하기 쉽게 만드는 법 영상을 토대로 정리한 내용입니다.

기사링크 : https://dev.to/anwar_nairi/design-an-easy-to-use-and-flexible-rest-endpoints-3fia

1. 좋은 데이터베이스 디자인에서 시작하라

어떠한 논리적인 체계가 있어야 사용자들에게 헷갈리지않고 정보를 전달할수 있다.
좋은 데이터베이스는 논리적인 체계를 만들기 좋다
결국은 RESTFUL API는 문서화를 해서 데이터를 활용하는 방식이기 때문에
좋은 데이터베이스 설계가 선행되야 좋은 REST API 문서를 작성하기 쉽다

ex) 고객이 계좌를 갖고 있다면 고객의 계좌와 관련된 데이터는
고객 테이블에서 시작해서 각 칼럼의 속성이 연관되어있는 다른 테이블의 데이터와 연결지어서 데이터를 구성하고 주고받는 방식이 좋다. (논리적인 구조를 완성시켜서 가는것이 좋다는 뜻으로 해석했습니다.)

{
  ...
  customers: [..., { customerId : { accounts } }, ... ]
  ...
}

데이터베이스 설계에서 하지 말아야 할것

• 엔티티 간의 반복되는 연결, 또는 원형으로 연결된(A->B->A 구조, A->B->C->D->E->A 등) 구조를 만들지 마라
• 새로운 디펜던시를 추가하는 경우에는 기존의 테이블을 많이 바꾸지 말고 추가할수 있어야 한다.
• 데이터베이스 normailzation(정규화)을 잘하면 위의 문제가 적으니 평소에 데이터베이스 normalization(정규화)를 잘하자

2. 바람직한 REST API 구조 예시

• url에 동사넣지 말고 명사넣자

• 반환받을, 업데이트할 데이터를 바탕으로 uri에 명시하자

• /api 는 도메인에 따라 생략할수도 안할수도 있다

• /user 를 복수로 /users 를 써도 무방

• put은 rest api 규약으로는 튜플에 필요한 모든 데이터(모든 attribute)를 보내주라고 명시- - 되어있지만 일부만 전달해서 업데이트하는 경우도 많다

• 규약대로면 일부 attribute 수정은 patch로, 전체 attirbute는 put으로 한다.

• HATEOAS 는 REST API 보다 더 엄격한 기준, 실무에서 잘 지키지는 않는다.

• 쿼리스트링을 활용해서 필터기능을 적용하면 좋다. ( ex) /api/task/{id}?select=task.id,task.user.id )

• 각 테이블에 타임스탬프는 적용해야한다. 데이터가 언제 업데이트 되었는지는 알아야 하기 때문.

• DB안의 id값을 보여주는건 굉장히 나쁜 습관(id를 유출하는거에 더해 무엇인지 알려주는 정보까지 포함하면 더 안좋음 !)