웹 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 캐싱 동작, 재시도 동작, 자원에 이전에 없었던 필드를 허용하는 관용성 등.

 

 

 

 

 

[출처]

APIGEE-WEB-API-DESIGN-THE-MISSING-LINK