퀄리티 높은 REST API 작성하기 🎨

이전에 작성한 올바른 API 작성하기에 이어 높은 퀄리티의 API를 작성하는 방법에 관한 아티클을 번역을 통해 가져와 봤습니다 :-)

다음은 API의 품질과 성능을 향상시키는 매우 구체적인 조치와 관행입니다.

1) 복수 명사 사용하기

• 대부분 잘 확립되어 있는 부분이지만 규칙에 따라 잘 사용해야 합니다.

  • GET/book/{book_id} -> GET/books/{book_id}

2) REST API 경로 세그먼트에 따라 데이터베이스를 모델링하지 않기

• 개발자가 전체 관계형 데이터베이스 모델을 URL 구조로 구축하는 경우가 있습니다. GET /books/{book_id}은 좋은 예시이고, /authors/{author_id}/books/{book_id}은 좋지 않은 GET입니다. 책 ID는 전세계적으로 고유하기에 저자 ID가 책에 엑세스하기 위한 URL의 일부가 되면 안 되기 때문입니다. 만약 book_id가 저자별로 공유한 경우 복합 URL이 적합할 수는 있죠.

3) 배열을 최상위 응답으로 반환하지 않기

• 앤드포인트의 최상위 응답은 배열이 아닌 객체여야 합니다. GET/books returns: {“data”:[{…book1…}], [{…book2…}]}은 좋은 예시이고 GET /books returns:[{…book1…}]은 좋지 않은 예시입니다. 배열을 반환하면 이전 버전과 호환되는 출력을 변경하기가 까다로워 권장되지 않습니다. 예를 들어 totalCount와 같은 페이지 매김 필드를 추가하는 것이 좋습니다.

4) 데이터베이스에 숫자값을 저장하는 경우 객체 식별자는 문자열을 사용하기

• {“id”: “456”}는 좋은 예시이고, {“id”: 456}는 좋지 않은 예시입니다. 문자열 ID는 구현 변경에 유연하며, 향후 개발자가 다양한 방식으로 시스템을 조정하는 데에 편리합니다.

5) "NOT Found"를 사용하기 위해 404를 사용하지 않기

• 리소스를 찾을 수 없음을 나타나는 데에 사용해야 하는 HTTP 사양 주장은 중요하나, 개발자는 GET/PUT/DELETE가 존재하지 않는 ID에 404를 반환하도록 하여 이를 문제 그대로 구현합니다. 그러나 존재하지 않는 ID에 대해 응답은 클라이언트에 2가지를 전달해야 합니다. 1) 서버가 요청을 이해했다. 2) 불행하게도 id를 찾을 수 없다. 404는 다양한 이유로 인해 발생할 수 있기 때문입니다.

6) 구조화된 오류 형식 사용하기

• 유저가 많고, 적절한 오류 형식이 없는 대규모 시스템 상에서는 자세한 오류 형식을 사용해야 합니다. 예를 들어 오류 메시지 - 오류 유형 - 원인과 같이 말이죠.

지금까지 퀄리티 높은 api를 작성하는 원칙에 대해 알아봤습니다.

해당 글에 대한 원본 글은 아래 링크에서 확인할 수 있습니다 !

https://medium.com/stackademic/creating-a-high-quality-rest-api-201819325356