REST URI 규칙-자원을 작성하는 동안 단수 또는 복수의 자원 이름

REST에 익숙하지 않고 일부 RESTful 서비스에서 업데이트 / 가져 오기 / 삭제 및 작성에 다른 리소스 URI를 사용하는 것으로 나타났습니다. 와 같은

• 작성- / resource (단일)를 사용하여 일부 위치에서 POST 메소드와 함께 / resources 사용 (복수 관찰 )
• 업데이트 -PUT 방법으로 / resource / 123 사용
• Get- GET 메소드와 함께 / resource / 123 사용

이 URI 명명 규칙에 대해 약간 혼란 스럽습니다. 자원 생성을 위해 복수 또는 단수를 사용해야하는 것은 무엇입니까? 그것을 결정할 때 기준은 무엇입니까?

사용의 전제 /resources는 "모든"자원을 나타내는 것입니다. 을 수행 GET /resources하면 전체 컬렉션을 반환 할 수 있습니다. POSTing to (으 /resources)로 컬렉션에 추가하고 있습니다.

그러나 개별 리소스는 / resource에서 사용할 수 있습니다. 을 수행하면 GET /resource이 요청은 의미가 없지만 /resource/123완벽하게 이해되므로 오류가 발생할 수 있습니다.

사용 /resource대신하는 것은 /resources당신이 말하는, 파일 시스템 및 파일의 모음 작업을하고 있다면 당신이 이런 짓을 했을까하는 것과 비슷 /resource개인과 "디렉토리"입니다 123, 456거기에 파일을 저장합니다.

어느 쪽이든 옳고 그른 것이 아니라 가장 좋아하는 것을 따라 가십시오.

나에게는 코드가 양쪽 끝에있을 것이기 때문에 코드에 직접 매핑 할 수있는 스키마를 갖는 것이 좋습니다 (자동화하기 쉽습니다).

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

나는 이것을하는 데 요점을 보지 못했고 그것이 최고의 URI 디자인이 아니라고 생각합니다. RESTful 서비스 사용자는 목록에 액세스하는지 또는 목록의 특정 리소스에 관계없이 목록 리소스의 이름이 동일 할 것으로 기대합니다. 목록 리소스를 사용하든 특정 리소스를 사용하든 관계없이 동일한 식별자를 사용해야합니다.

복수형

• 단순 -모든 URL은 동일한 접두어로 시작합니다
• 논리 - orders/주문의 색인 목록을 가져옵니다.
• 표준 -가장 널리 채택 된 표준과 압도적 인 대다수의 공용 및 개인 API가 뒤 따릅니다.

예를 들면 다음과 같습니다.

GET /resources -자원 항목의 목록을 반환

POST /resources -하나 이상의 자원 항목을 작성합니다

PUT /resources -하나 이상의 자원 항목을 업데이트합니다

PATCH /resources -하나 이상의 리소스 항목을 부분적으로 업데이트

DELETE /resources -모든 자원 항목을 삭제합니다

단일 자원 항목의 경우 :

GET /resources/:id- :id매개 변수를 기반으로 특정 자원 항목을 리턴합니다.

POST /resources/:id -지정된 ID를 가진 하나의 자원 항목을 작성합니다 (검증 필요).

PUT /resources/:id -특정 자원 항목을 업데이트

PATCH /resources/:id -특정 자원 항목을 부분적으로 업데이트

DELETE /resources/:id -특정 자원 항목을 삭제합니다

단수의 옹호자들에게 다음과 같이 생각하십시오. 누군가에게 물어보고 order한 가지 또는 물건의 목록을 기대 하시겠습니까 ? 그렇다면 왜 입력 할 때 서비스가 목록을 반환해야 /order합니까?

단수형

편의 사물에는 불규칙 복수형 이름이있을 수 있습니다. 때때로 그들은 하나도 없습니다. 그러나 단수 이름은 항상 있습니다.

예를 들어 CustomerAddress를 통한 CustomerAddress

이 관련 리소스를 고려하십시오.

이것은 /order/12/orderdetail/12보다 읽기 쉽고 논리적 /orders/12/orderdetails/4입니다.

데이터베이스 테이블

자원은 데이터베이스 테이블과 같은 엔티티를 나타냅니다. 논리적 단수 이름이 있어야합니다. 다음은 테이블 이름에 대한 답변 입니다.

클래스 매핑

수업은 항상 단수입니다. ORM 도구는 클래스 이름과 동일한 이름으로 테이블을 생성합니다. 점점 더 많은 도구가 사용됨에 따라 단일 이름이 표준이되고 있습니다.

REST API 개발자의 딜레마 에 대해서 더 읽어보세요.

가장 보편적 인 관행은 복수가 사용되는 RESTful api /api/resources/123이지만, 복수의 이름보다 단수의 이름이 더 적절하고 표현적인 경우가 있습니다. 일대일 관계의 경우입니다. 구체적으로 대상 항목이 가치 객체 (도메인 기반 디자인 패러다임) 인 경우.

모든 자원이 일대일로 accessLog가치 객체로 모델링 될 수 있다고 가정하자. 즉 개체가 아니기 때문에 ID가 없다. 로 표현 될 수 있습니다 /api/resources/123/accessLog. 일반적인 동사 (POST, PUT, DELETE, GET)는 의도와 관계가 실제로 일대일이라는 사실을 적절하게 표현합니다.

단일 형식이 일반적으로 허용되는 데이터베이스 테이블 이름의 유행 추세를 따르십시오. 그곳에 다녀 왔으니 재사용하자.

테이블 이름 딜레마 : 단수와 복수 이름

너무 많은 사람들이 복수 명사 악 대차를 타는 것을보고 놀랐습니다. 단수에서 복수로 변환 할 때 불규칙 복수 명사를 관리하고 있습니까? 당신은 고통을 즐기십니까?

참조 http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm를

불규칙 복수형에는 여러 유형이 있지만 가장 일반적입니다.

복수의 예를 형성하는 명사형

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

API 소비자의 관점에서 엔드 포인트는 예측 가능해야합니다.

이상적으로는 ...

1. GET /resources 리소스 목록을 반환해야합니다.
2. GET /resource 400 레벨 상태 코드를 반환해야합니다.
3. GET /resources/id/{resourceId} 하나의 리소스가있는 컬렉션을 반환해야합니다.
4. GET /resource/id/{resourceId} 자원 객체를 반환해야합니다.
5. POST /resources 리소스를 일괄 생성해야합니다.
6. POST /resource 자원을 만들어야합니다.
7. PUT /resource 자원 객체를 업데이트해야합니다.
8. PATCH /resource 변경된 속성 만 게시하여 리소스를 업데이트해야합니다.
9. PATCH /resources 변경된 속성 만 게시하는 리소스를 일괄 업데이트해야합니다.
10. DELETE /resources모든 자원을 삭제해야합니다. 농담 : 400 상태 코드
11. DELETE /resource/id/{resourceId}

이 접근 방식은 가장 유연하고 기능이 풍부하지만 개발에 가장 많은 시간이 소요됩니다. 따라서 급한 경우 (항상 소프트웨어 개발의 경우) 엔드 포인트 resource또는 복수형의 이름을 지정하십시오 resources. 단수형은 모든 복수형이 's'로 끝나는 것이 아니기 때문에 프로그래밍 방식으로 검사하고 평가할 수있는 옵션을 제공하기 때문에 선호합니다.

무엇이든, 가장 일반적으로 사용되는 실습 개발자가 선택한 이유는 복수형을 사용하는 것입니다. 이것은 궁극적으로 내가 선택한 경로이며 인기있는 api를 githuband 처럼 보면 twitter이것이 그들이하는 일입니다.

결정 기준은 다음과 같습니다.

1. 시간 제약은 무엇입니까?
2. 소비자는 어떤 작업을 수행 할 수 있습니까?
3. 요청 및 결과 페이로드는 어떤 모양입니까?
4. 리플렉션을 사용하고 코드에서 URI를 구문 분석하고 싶습니까?

따라서 그것은 당신에게 달려 있습니다. 당신이하는 일이 무엇이든

내 두 센트 : 복수에서 단수로 또는 그 반대로 시간을 보내는 방법은 CPU 사이클을 낭비합니다. 나는 구식이 될 수도 있지만 내 시대에는 같은 것이라 불렀습니다. 사람들에 관한 방법을 어떻게 찾습니까? 바람직하지 않은 부작용없이 사람과 사람 모두를 정기적으로 처방하지는 않습니다.

영어 복수는 매우 임의적 일 수 있으며 코드를 불필요하게 방해합니다. 하나의 명명 규칙을 고수하십시오. 컴퓨터 언어는 자연 언어를 흉내내는 것이 아니라 수학적으로 명확해야합니다.

단순성과 일관성을 위해 단일 형식을 사용하는 것이 좋습니다.

예를 들어 다음 URL을 고려하십시오.

/ 고객 / 1

고객을 고객 수집으로 취급하지만 단순성을 위해 수집 부분이 제거됩니다.

또 다른 예:

/ 장비 / 1

이 경우 장비는 올바른 복수형이 아닙니다. 따라서 장비 수집으로 취급하고 단순화를 위해 수집을 제거하면 고객 사례와 일치합니다.

경로의 ID는 목록의 색인과 동일하게보아야하며 그에 따라 이름 지정이 진행되어야합니다.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

그러나 일부 리소스는 경로가 하나만 있거나 사용자가 둘 이상에 액세스 할 수 없으므로 경로에 ID를 사용하지 않으므로 목록에 없습니다.

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

명명 규칙을 사용하면 일반적으로 "하나만 골라 고수"라고 말하는 것이 안전합니다.

그러나 많은 사람들에게 REST를 설명한 후 엔드 포인트를 파일 시스템의 경로 로 나타내는 것이 가장 표현적인 방법입니다.
상태가없고 (파일이 존재하거나 존재하지 않음) 계층 적이며 단순하며 친숙합니다. 로컬 또는 http를 통해 정적 파일에 액세스하는 방법을 이미 알고 있습니다.

이러한 맥락에서 언어 규칙은 다음과 같은 범위 내에서만 가능합니다.

디렉토리는 여러 파일 및 / 또는 하위 디렉토리를 포함 할 수 있으므로 이름 은 복수 형식 이어야 합니다.

그리고 나는 그것을 좋아한다.
반면 디렉토리는 디렉토리이지만 원하는 경우 "자원 또는 다중 자원"으로 이름을 지정할 수 있습니다. 그것은 정말로 중요한 것이 아닙니다.

중요한 것은 "resourceS"라는 디렉토리에 "123"이라는 파일을 넣은 경우 (을 통해) 파일을 /resourceS/123통해 액세스 할 수 없다는 것 /resource/123입니다.

현재 액세스하는 리소스의 수에 따라 복수에서 단일로 변경하는 것이 현명하게 만들려고하지 마십시오. 계층 적 시스템.

참고 : 기술적으로 "기호 링크"를 만들 수 있으므로를 /resources/123통해 액세스 할 수도 /resource/123있지만 전자는 여전히 존재해야합니다!

한 번 봐 가지고 구글 의 자원 이름 : API 디자인 가이드 명명 자원에 대한 또 다른 테이크를.

한마디로 :

• 컬렉션은 복수형으로 명명됩니다.
• 개별 리소스는 문자열로 이름이 지정됩니다.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /name@example.com | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

이 주제에 대해 생각하고 있다면 읽을 가치가 있습니다.

Postman (또는 유사한 툴)을 사용하여 리소스 API를 개발하고 테스트하는 경우 GET에서 PUT으로 POST 등을 전환 할 때 URI를 편집 할 필요가 없습니다. .

두 표현 모두 유용합니다. 나는 편의를 위해 단기간 동안 단수를 사용했는데, 활용은 어려울 수 있습니다. 엄격하게 단일 REST API를 개발 한 경험을 통해 엔드 포인트를 소비하는 개발자는 결과의 모양이 확실하지 않습니다. 이제 응답의 모양을 가장 잘 나타내는 용어를 사용하는 것을 선호합니다.

모든 리소스가 최상위 수준이면 단일 표현으로 벗어날 수 있습니다. 변곡을 피하는 것이 큰 승리입니다.

관계에 대한 쿼리를 나타 내기 위해 일종의 딥 링크를 수행하는 경우 엄격한 규칙을 사용하여 API를 작성하는 개발자에게 도움을 줄 수 있습니다.

내 규칙은 URI의 각 수준에서 상위 리소스와의 상호 작용을 설명하고 있으며 전체 URI는 검색 대상을 암시 적으로 설명해야한다는 것입니다.

다음과 같은 모델이 있다고 가정합니다.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

클라이언트가 특정 사용자의 특정 친구의 관리자를 얻을 수있는 리소스를 제공해야하는 경우 다음과 같이 보일 수 있습니다.

GET /users/{id}/friends/{friendId}/manager

다음은 몇 가지 예입니다.

• GET /users -글로벌 사용자 콜렉션에 사용자 자원을 나열하십시오.
• POST /users -글로벌 사용자 콜렉션에서 새 사용자 작성
• GET /users/{id} -글로벌 사용자 콜렉션에서 특정 사용자를 검색
• GET /users/{id}/manager -특정 사용자의 관리자 확보
• GET /users/{id}/friends -사용자의 친구 목록을 얻습니다.
• GET /users/{id}/friends/{friendId} -사용자의 특정 친구를 얻으십시오
• LINK /users/{id}/friends -이 사용자에게 친구 연결 추가
• UNLINK /users/{id}/friends -이 사용자로부터 친구 연결을 제거

각 레벨이 수행 될 수있는 상위에 어떻게 맵핑되는지 확인하십시오. 동일한 객체에 대해 다른 부모를 사용하는 것은 반 직관적입니다. 에 리소스를 검색하면 GET /resource/123새 리소스를 생성해야한다는 표시가 없습니다.POST /resources

나는 대부분의 사람들이 복수를 사용할 것인지 단수를 사용할 것인지를 결정하는 사이에 있다는 것을 알고 있습니다. 여기서 해결되지 않은 문제는 고객이 사용중인 클라이언트를 알아야하며 항상 실수를 할 가능성이 있다는 것입니다. 이것은 내 제안에서 비롯된 것입니다.

둘 다 어때요? 그리고 그것은 전체 API에 단수를 사용하고 복수 형태로 된 요청을 단수 형태로 전달하는 경로를 만듭니다. 예를 들면 다음과 같습니다.

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

당신은 그림을 얻는다. 아무도 잘못하지 않고 최소한의 노력만으로도 고객은 항상 올바른 결과를 얻을 수 있습니다.

이론적으로는 무엇이든지 모호성이있을 수 있기 때문에 {id}URL 의 일부가 하위 리소스와 겹치는 것을보고 싶지 않습니다 id. 서로 다른 개념 (식별자와 하위 리소스 이름)을 혼합하고 있습니다.

비슷한 문제가 종종에서 볼 수 있습니다 enum당신은 폴더가있을 때, 상수 또는 다른 개념이 (혼합 예를 들어 구조물, 폴더 Tigers, Lions그리고 Cheetahs다음도라는 폴더 Animals같은 수준은 - 하나의 부분 집합으로이 말도 안돼 다른).

일반적으로 엔드 포인트의 마지막 명명 된 부분은 한 번에 하나의 엔티티를 처리하는 경우 단수 여야하고 엔티티 목록을 처리하는 경우 복수 여야합니다.

따라서 단일 사용자를 다루는 엔드 포인트 :

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

그런 다음 사용자에 대한 쿼리를 수행하기위한 별도의 리소스가 있으며 일반적으로 목록을 반환합니다.

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

다음은 특정 사용자를 다루는 하위 리소스의 예입니다.

GET /user/{id}/friends -> Returns a list of friends of given user

친구를 사귀십시오 (다 대다 링크).

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

모호성이 없으며 자원의 복수 또는 단수 이름은 사용자가 기대할 수있는 것 (목록 또는 객체)에 대한 힌트입니다. 에 대한 제한은 없으므로 id이론적 new으로 (잠재적 미래) 하위 리소스 이름과 겹치지 않고 ID 를 가진 사용자를 가질 수 있습니다.

Singular를 사용하고 "Business Directory"와 같은 영어 규칙을 활용하십시오.

"Book Case", "Dog Pack", "Art Gallery", "Film Festival", "Car Lot"등 많은 것들이이 방식으로 읽 힙니다.

이것은 URL 경로를 왼쪽에서 오른쪽으로 편리하게 일치시킵니다. 왼쪽의 상품 유형입니다. 오른쪽에 유형을 설정하십시오.

않습니다 GET /users정말 지금까지 사용자 세트를 가져? 보통은 아닙니다. 키와 사용자 이름이 포함 된 스텁 세트를 가져옵니다. /users어쨌든 실제로는 아닙니다 . 사용자 인덱스이거나 "사용자 인덱스"입니다. 왜 그렇게 부르지 않습니까? 그것은이다 /user/index. set 유형의 이름을 지정 했으므로 쿼리 매개 변수 (예 : user/phone-list또는)에 의존하지 않고 사용자의 다른 투영을 보여주는 여러 유형을 가질 수 있습니다 /user/mailing-list.

그리고 User 300은 어떻습니까? 아직 /user/300입니다.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

마지막으로 HTTP는 단일 요청에 대한 단일 응답 만 가질 수 있습니다. 경로는 항상 단수의 무언가를 말합니다.

나에게 복수형은 컬렉션을 조작하는 반면, 단수형은 해당 컬렉션 내의 항목을 조작합니다 .

수집 은 GET / POST / DELETE 메소드를 허용합니다

GET / PUT / DELETE 방법을 허용하는 항목

예를 들어

POST on / students 는 학교에 새로운 학생을 추가 할 것입니다.

에 삭제 / 학생 학교의 모든 학생을 제거합니다.

/ student / 123의 DELETE 는 학교에서 학생 123을 제거합니다.

중요하지 않은 것처럼 느껴질 수도 있지만 일부 엔지니어는 때때로 ID를 잊어 버립니다. 경로가 항상 복수이고 삭제를 수행 한 경우 실수로 데이터를 지울 수 있습니다. 단수의 ID가 없으면 404 경로를 찾을 수 없습니다.

API가 여러 학교를 노출해야하는 경우 예제를 추가로 확장하려면

DELETE에 / 학교 / ABC / 학생들은 학교에서 모두에게 학생을 제거합니다 abc.

올바른 단어를 선택하는 것이 때로는 어려운 일이지만, 수집을 위해 복수를 유지하는 것을 좋아합니다. 예 cart_items또는 cart/items올바른 느낌. 반대로 삭제 cart는 카트 오브젝트를 삭제하지만 카트 내의 항목은 삭제하지 않습니다.).

어때요?

/resource/(아니요 /resource)

/resource/ "resource"라는 폴더가 있고 "resouce"폴더라는 것을 의미합니다.

또한 데이터베이스 테이블의 명명 규칙이 동일하다고 생각합니다. 예를 들어 'user'라는 테이블은 "user table"이며 "user"라는 것이 포함되어 있습니다.

복수 ( /resources)와 단수 ( /resource/{id})를 모두 사용하는 것이 좋습니다. 왜냐하면 논리 수집이 자원 수집 작업과 단일 자원 작업 간의 논리를 더 명확하게 구분한다고 생각하기 때문입니다.

이것의 중요한 부작용으로, 누군가 API를 잘못 사용하는 것을 막을 수 있습니다. 예를 들어, 사용자가 다음과 같이 ID를 매개 변수로 지정하여 자원을 잘못 가져 오려고 시도하는 경우를 고려하십시오.

GET /resources?Id=123

이 경우 복수 버전을 사용하는 경우 서버는 대부분 Id 매개 변수를 무시하고 모든 리소스 목록을 반환합니다. 사용자가주의하지 않으면 호출이 성공했다고 생각하고 목록의 첫 번째 자원을 사용합니다.

반면에 단수형을 사용할 때 :

GET /resource?Id=123

서버는 ID가 올바른 방식으로 지정되지 않았기 때문에 오류를 반환 할 가능성이 높으며 사용자는 무언가 잘못되었음을 인식해야합니다.