원문: Compose your API surface with Data API builder custom paths
Data API Builder의 새로운 복합 REST 경로 지원은 사소한 구성 개선처럼 보일 수 있지만, 실제로는 오래된 API 설계 긴장을 해결합니다: 데이터베이스 토폴로지가 공개 엔드포인트 설계로 누출되는 문제입니다.
기본 엔티티 기반 경로는 빠른 시작에 좋습니다. 장기 제품 API에는 종종 틀렸습니다. 실제 시스템은 비즈니스 개념, 소유권 경계, 소비자 멘탈 모델과 일치하는 경로 구조가 필요합니다.
그래서 이 DAB 변경이 중요한 이유입니다. 생성된 API 편의성을 유지하면서 더 깔끔한 도메인 우선 표면을 제공할 수 있습니다.
내 독단적인 의견은 간단합니다: 프로덕션에서 API 경로 구조가 원시 테이블 이름을 반영한다면, 보통 백엔드 편의성을 위해 클라이언트 명확성을 희생하고 있는 것입니다.
사용자 정의 경로를 통해 팀은 더 나은 경계를 모델링할 수 있습니다: 영업, 청구, 지원, 파트너별 표면 등. 이것이 적절한 API 거버넌스를 대체하지는 않지만, DAB 사용자에게 제품 언어와 경로 설계를 정렬할 실용적인 방법을 제공합니다.
이 기능을 도입하는 팀을 위한 실용적 가이드
- 경로를 임시로 추가하기 전에 명명 정책을 정의하세요. 일관성 없는 하위 세그먼트는 장기적인 혼란이 됩니다.
- 엔드포인트를 조직도가 아닌 경계 컨텍스트(bounded contexts)에 매핑하세요. 팀은 변하고, 도메인 의미론은 안정적이어야 합니다.
- 경로 구조를 버전 전략의 일부로 취급하고 호환성이 깨지는 변경을 명시적으로 문서화하세요.
- 사용자 정의 경로 구조를 따라 권한 부여 동작을 검증하여 경로 명확성과 보안 명확성이 함께 가도록 하세요.
DAB에서 일반적으로 제가 감사하게 생각하는 것은 레버리지 모델입니다: 반복적인 컨트롤러 코드를 작성하지 않고도 페이지네이션, 필터링, 프로젝션 및 기타 엔드포인트 메커니즘을 얻을 수 있습니다. 사용자 정의 경로는 API 아키텍트의 가장 큰 이의 제기 중 하나를 줄여 그 레버리지를 더 프로덕션 준비 상태로 만듭니다.
한 가지 주의사항이 있습니다. 더 나은 경로 구성은 생성이 쉽게 느껴지기 때문에 팀이 너무 많은 것을 너무 빨리 노출하도록 유혹할 수 있습니다. 가드레일은 여전히 중요합니다: 엔티티 노출을 의도적으로 유지하고, 정책을 중앙에서 적용하며, 내부 스키마 실험에서 우발적인 공개 계약을 구축하지 않도록 하세요.
전달 압박을 받는 .NET 조직에게 이 기능은 규율을 가지고 사용하면 생산성 향상입니다. 수제 API 레이어보다 빠르게 움직일 수 있으면서도 일관되고 비즈니스 친화적인 엔드포인트 표면을 유지할 수 있습니다.
결론: DAB 사용자 정의 경로는 URL을 예쁘게 만드는 것에 관한 것이 아닙니다. 생성된 엔드포인트의 운영 효율성을 유지하면서 API 설계 의도를 되찾는 것에 관한 것입니다.
