웹 API 설계: 놓치기 쉬운 핵심 - 데이터 지향 설계 패러다임
데이터 지향 설계 패러다임
REST API는 엔티티를 조작하는 함수 집합보다는, 노출하려는 문제 도메인의 기본 엔티티에 중점을 둡니다. 머리말에서 소개한 예를 따르면, 우리 문제 도메인은 개와 그 주인을 추적하는 것이라고 가정해봅시다. 여기서 우리가 노출할 주요 엔티티는 다음을 포함할 수 있습니다:
• 알려진 개들의 컬렉션. 이 컬렉션의 URL은 https://dogtracker.com/dogs 일 수 있습니다.
• 개별 개들. 각 개는 고유한 URL을 갖습니다. 각 개의 URL 형식은 곧 논의할 것입니다. 우리는 주인에 대해서도 이와 유사한 무언가가 필요합니다.
데이터 지향 접근 방식이 왜 유용할까요?
개별 개의 URL과 HTTP 프로토콜의 작동 방식을 알고 있다면, 이미 여러 가지 작업을 어떻게 수행할지 알 수 있습니다. 예를 들어, GET 메소드를 사용해 그 개의 세부 정보를 가져오고, DELETE 메소드를 사용해 개를 삭제하며, PATCH 또는 PUT 메소드를 사용해 개의 속성을 수정할 수 있음을 알고 있습니다. 이 작업들을 성공적으로 사용하려면 개의 속성을 이해해야 하지만, 그 작업들의 기본적인 메커니즘은 이미 알고 있는 것입니다. 개에게 주인이나 의료 기록 같은 관련된 엔티티가 있다면, 이 엔티티들 역시 비슷한 방식으로 조작할 수 있습니다.
마찬가지로, 개들의 컬렉션 URL을 알면, POST 메소드를 사용해 새로운 개를 생성하거나 GET 메소드를 사용해 기존 개들을 찾을 수 있습니다. 검색 범위를 좁히기 위해 컬렉션을 필터링하는 방법을 배워야 할 수도 있지만, 잘 설계된 API에서는 URL에 쿼리 파라미터를 추가하여 필터링을 수행하는 것이 일반적입니다.
반면, 함수 지향 API에서는 변동성이 더 크고, 배워야 할 세부 사항이 훨씬 더 많습니다. 다음 예시 표를 참고해보세요:
| ... | ... |
| /getAllDogs | /getAllLeashedDogs |
| /verifyLocation | /verifyVeterinarianLocation |
| /feedNeeded | /feedNeededFood |
| /createRecurringWakeup | /createRecurringMedication |
| /giveDirectOrder | /doDirectOwnerDiscipline |
| /checkHealth | /doExpressCheckupWithVeterinarian |
| /getRecurringWakeUpSchedule | /getRecurringFeedingSchedule |
| /getLocation | /getHungerLevel |
| /getDog | /getSquirrelsChasingPuppies |
| /newDog | /newDogForOwner |
| /getNewDogsSince | /getNewDogsAtKennelSince |
| /getRedDogs | /getRedDogsWithoutSiblings |
| /getSittingDogs | /getSittingDogsAtPark |
| /setDogStateTo | /setLeashedDogsStateTo |
| /replaceSittingDogsWithRunningDogs | |
| /saveDog | /saveMommaDogsPuppies |
| ... | ... |
이러한 함수들로 구성된 API를 사용하려면, 개가 무엇인지와 그 고유한 속성에 대해 이해해야 할 뿐만 아니라, 해당 API의 함수에 특화된 많은 세부 사항도 배워야 합니다. 이 세부 사항은 학습을 돕기 위한 명확한 구조나 패턴이 없기 때문에, 학습 부담이 크며, 이 지식을 습득한다고 해도 다음에 배워야 할 API에는 큰 도움이 되지 않습니다. 이러한 스타일의 API들 간에는 공통적인 요소가 거의 없거나 아예 없습니다.
HTTP와 REST를 기반으로 API를 설계할 때의 가치는 API에 일관성을 부여하는 데 있습니다. 본질적으로 HTTP를 네이티브로 사용할 때는 별도의 API를 발명할 필요가 없습니다. HTTP 자체가 API를 제공하며, 우리는 자원의 데이터를 정의하기만 하면 됩니다. REST에서는 이를 일관된 인터페이스 제약이라고 부릅니다. 월드 와이드 웹에서는 이 개념이 단순히 API를 배우기 쉽게 만드는 것을 넘어서, 웹 브라우저나 검색 봇과 같은 범용 소프트웨어를 모든 웹사이트에서 작동 가능하게 하는 중요한 요소입니다.
API 설계 요소
다음의 API 설계 측면들은 모두 중요하며, 이들이 함께 API를 정의합니다:
• 자원의 표현 방식 — 자원의 표현이 구조화된 데이터(바이트나 문자 스트림이 아닌 경우)라면, 자원의 필드 정의와 관련된 자원으로의 링크를 포함합니다.
• 표준 HTTP 헤더(때로는 사용자 정의 헤더 포함)의 사용.
• 자원의 데이터를 기반으로 자원을 찾기 위한 API의 쿼리 인터페이스를 정의하는 URL과 URI 템플릿.
• 클라이언트가 따라야 할 필수 동작 — 예를 들어, DNS 캐싱 동작, 재시도 동작, 자원에 이전에 없었던 필드를 허용하는 관용성 등.
[출처]