더 많은 생성기, 글쓰기 도구, 스토리텔링 자료를 만나보세요.
API 엔드포인트 명명 배경
엔드포인트 이름은 제품 언어와 구현 세부 정보 사이의 중간 역할을 합니다. 좋은 엔드포인트 이름은 팀원이 컨트롤러, 사양 또는 변경 로그를 열어보기 전에 해당 경로가 무엇을 하는지 명확하게 알려줘야 합니다. REST 스타일 API에서 엔드포인트 이름은 일반적으로 리소스 명확성, 메서드 의도, 범위, 버전 관리 및 액세스 규칙 간의 균형을 유지합니다. "Fetch Export Job Status"와 같은 이름은 "Run Old Billing Routine"과는 다른 개념적 모델을 제시합니다. 전자는 명확하고 검토 가능한 반면, 후자는 레거시 액션 모음을 암시합니다. 이 생성기는 세련된 패턴과 문제가 있는 패턴을 모두 살펴보므로 공개 API에 적합한 이름, 관리자 전용으로 접근해야 하는 이름, 그리고 클라이언트에 도달하기 전에 이름을 변경해야 하는 이름을 구분할 수 있습니다.
생성된 엔드포인트 이름 사용 방법
이름을 실제 리소스에 매핑
먼저 어떤 명사가 해당 액션을 소유하는지 파악합니다. 사용자, 송장, 업로드, 세션, 조직, 내보내기 및 웹훅은 모두 서로 다른 명명 규칙을 제시합니다. 생성된 이름이 명사는 맞지만 동사가 틀린 경우, 명사는 그대로 두고 동작을 다시 작성하세요. 동사는 맞는 것 같지만 리소스가 모호한 경우, API 참조 테이블에서 의미가 통할 때까지 범위를 좁히세요.
범위 및 접근 권한 존중
관리자 전용 경로, 공개 읽기 전용 경로, 백그라운드 작업 트리거 및 내부 도구 엔드포인트는 서로 바꿔 쓸 수 있는 이름이 되어서는 안 됩니다. 이러한 이름은 운영상의 위험을 수반합니다. 삭제, 취소, 제거 또는 취소와 같은 파괴적인 작업은 명확하게 명시해야 합니다. 상태 확인은 변경하는 것이 아니라 관찰 가능한 것처럼 들려야 합니다. 웹훅 콜백은 수신되는 이벤트를 명확하게 나타내야 합니다.
중요한 경우 버전 관리를 명확하게 표시
버전 관리 및 사용 중단 예정 경로는 팀의 마이그레이션을 돕는 이름을 사용해야 합니다. 생성된 사용 중단 이름을 사용하여 호환성 엔드포인트, 서비스 종료 경고, 제거된 필드 맵 또는 대체 미리 보기를 표시하세요. 목표는 장식적인 이름 지정이 아닙니다. 목표는 기존 고객, 신규 고객 및 내부 도구가 중복될 때 모호함을 줄이는 것입니다.
팀에서 사용할 경우, 선택한 이름을 코드와 문서 간의 계약으로 간주하십시오. 이름이 리소스, 효과, 접근 수준 및 수명 주기를 몇 단어로 설명할 수 없다면, 경로, 스키마 또는 사양에 너무 많은 수정 작업을 요구하는 것일 수 있습니다.
이름 선택을 위한 실용적인 팁
- item, thing, data 또는 stuff와 같은 모호한 객체보다는 명확한 리소스 명사를 선호하세요.
- 특히 변경, 내보내기 및 백그라운드 작업의 경우 경로 동작과 일치하는 동사를 사용하세요.
- 관리자, 내부, 위험 또는 테넌트 범위 작업은 명확하게 표시하세요.
- process 또는 action과 같은 중립적인 단어 뒤에 부작용을 숨기는 이름은 피하세요.
- 웹훅 이름은 수신 또는 처리되는 이벤트를 중심으로 하세요.
- 로그, 문서 및 지원 노트에서 이름이 여전히 유효한지 확인하세요.
엔드포인트 언어 개선을 위한 프롬프트
눈에 띄는 결과가 나오면 주변 API 표면과 비교하여 테스트하세요. 엔드포인트 이름은 개별적인 레이블보다는 패밀리 형태로 사용하는 것이 가장 효과적입니다. 다음 질문들을 활용하여 대략적인 후보를 팀에서 반복할 수 있는 규칙으로 만들어 보세요.
- 이 이름에 해당하는 경로 또는 컨트롤러에 정확히 어떤 리소스가 나타날까요?
- 엔드포인트는 읽기 전용, 변경 가능, 파괴 가능, 내부, 공개 또는 테넌트 범위 중 어떤 유형인가요?
- OpenAPI 요약에서도 동일한 표현이 명확하게 전달될까요?
- 이름이 보안 및 지원 팀에 충분한 위험 요소를 알려줄까요?
- 향후 버전에서도 어색한 예외 없이 이 패턴을 유지할 수 있을까요?
- 어떤 인접 엔드포인트가 동일한 동사 또는 명사 패턴을 공유해야 할까요?
API 엔드포인트 생성기는 어떻게 작동하나요?
리소스, 스코프, 버전, 웹훅, 업로드, 검색, 작업, 상태 확인 및 삭제 작업과 같은 API별 관점을 중심으로 작성된 짧은 엔드포인트 이름을 표시합니다. 클릭할 때마다 복사, 수정 또는 조합할 수 있는 이름이 표시됩니다.
API 엔드포인트 생성기를 특정 이름으로 지정할 수 있습니까?
예. API 표면에 맞는 각도가 나올 때까지 다시 생성한 다음, 여러 이름을 조합하여 메서드, 리소스, 범위 및 버전 관리 모델에 맞는 규칙을 만드세요.
이름이 독창적이고 안전하게 사용할 수 있나요?
이 이름들은 이 생성기를 위해 작성되었으며 개인적인 용도 및 대부분의 상업적인 용도로 사용할 수 있습니다. 규제 대상 제품, 공개 API 또는 브랜드에 중요한 시스템의 경우, 자체 기준에 따라 이름을 검토하십시오.
이름을 몇 개까지 생성할 수 있나요?
생성기를 반복해서 다시 실행하고 후보를 계속 수집할 수 있습니다. 빠른 탐색을 위해 설계되었으므로 고정된 할당량을 추적하지 않고 일반 REST 이름, 관리자 경로, 웹훅 및 내부 레이블을 비교할 수 있습니다.
마음에 드는 이름은 어떻게 저장하나요?
결과를 클릭하여 복사하거나 하트 또는 저장 아이콘을 사용하여 경로 패밀리, 명명 규칙 및 최종 API 문서 문구를 비교하는 동안 관심 있는 목록을 유지할 수 있습니다.
좋은 API 엔드포인트 이름에는 어떤 것이 있나요?
이 생성기에는 수천 개의 랜덤 API 엔드포인트 이름가 있습니다. 시작할 수 있도록 몇 가지 예시를 소개합니다:
- Create Customer Profile
- List Project Comment Threads
- Admin Suspend User Login
- Browse Public Catalog
- Bulk Import Customer Records
- Receive Payment Settled Webhook
- Fetch Deprecated V1 Profile
- Begin OAuth Authorization
- Export Daily Usage Metrics
- Create Direct Upload URL
제작자 소개
The Story Shack의 모든 아이디어 생성기와 글쓰기 도구는 스토리텔러이자 개발자인 Martin Hooijmans가 정성껏 만들고 있습니다. 낮에는 기술 솔루션을 만드는 일을 하고, 자유 시간에는 읽기, 쓰기, 게임, 롤플레잉 등 이야기 속으로 깊이 들어가는 것을 좋아합니다. 떠오르는 거의 모든 이야기 활동을 저는 아마 즐기고 있을 겁니다. The Story Shack은 전 세계 스토리텔링 커뮤니티에 제가 돌려드리는 방식입니다. 제가 아이디어를 실제로 살아 움직이게 만드는 거대한 창작의 공간이기도 합니다. 들러 주셔서 감사하고, 이 도구가 마음에 드셨다면 다른 도구들도 꼭 몇 개 더 둘러보세요!
저장한 아이디어 
