RESTful API 리소스 명명 가이드(URI 명명)

API 설계와 관련하여 일관되게 준수되는 API 리소스 명명 규칙을 갖는 것이 매우 중요합니다. 와 결합하여 API 액세스를 표준화하고 잠재적인 보안 문제를 줄이는 데 도움이 됩니다. 다음은 직관적이고 사용하기 쉬운 API를 설계하는 데 도움이 되고 프런트엔드 개발자가 당신을 사랑하게 만들 REST API 리소스 및 엔드포인트 이름 지정에 대한 빠른 가이드입니다 😉.

리소스로서의 URI(명사)

나를 포함하여 API 개발자가 저지르는 가장 일반적인 실수 중 하나는 REST URI에서 명사와 동사를 오용하는 것입니다. 다음은 REST URI 이름 지정을 이해하는 데 도움이 되는 간단한 참고 사항입니다.

REST APIs are used to get and manipulate resources (nouns), not actions (verbs). Therefore, REST URIs should not indicate any kind of action or CRUD (Create, Read, Update, Delete) functionality.

예:

// Get all user resources
GET "https://example.com/api/v1/users" // Correct
GET "https://example.com/api/v1/listUsers" // Wrong

// Update a single photo resource
PUT "https://example.com/api/v1/photos/{id}" // Correct
PUT "https://example.com/api/v1/updatePhoto/{id}" // Wrong

복수화된 리소스

singleton 또는 함수 리소스가 없으면 모든 리소스 이름을 복수화해야 합니다.

예

"/users/{id}"
"/schema" // Singleton resource
"/auth/login" // Function resource

자원 계층

리소스에는 하위 컬렉션 리소스가 있을 수 있습니다. 일반적으로 개별 리소스와 컬렉션 간의 계층 구조는 슬래시를 사용하여 표시됩니다.

예시:
단일 고객 리소스에 속하는 모든 주문 리소스를 가져옵니다.

GET "/customers/123/orders"

문자 및 대시

리소스 이름은 소문자만 사용해야 합니다. 여러 단어로 된 리소스 이름의 경우 밑줄 또는 카멜 케이스 규칙 대신 대시를 사용하십시오.

예시

"/users/123/pending-orders" // Correct
"/users/123/pendingOrders" // Wrong
"/users/123/pending_orders" // Wrong

추가 팁

요약 없음. /users/{id}/phone-number 대신 /users/{id}/tel-no

뒤에 슬래시가 없습니다. /users/{id}/pending-orders 대신 /users/{id}/pending-orders/

일관성이 핵심입니다

쿼리 매개변수를 사용하여 URI 모음을 필터링, 정렬 또는 제한합니다. /users?country=ZM&sort=createdAt&limit=100

RESTFul API와 관련하여 다른 모범 사례를 공유하려면 댓글을 달아주세요.