7.2. Definition

Notice that the “item” resource type is still full of redundancies. Let’s see how traits can help eliminate them. We’ll start by extracting a trait for any method containing a request body:

traits:
  hasRequestItem:
    body:
      application/json:
        type: <<"typeName">>

Now let’s extract traits for methods whose normal responses contain bodies:

  hasResponseItem:
    responses:
      200:
        body:
          application/json:
            type: <<"typeName">>
  hasResponseCollection:
    responses:
      200:
        body:
          application/json:
            type: <<"typeName">>[]

Finally, here’s a trait for any method that could return a 404 error response:

  hasNotFound:
    responses:
      404:
        body:
          application/json:
            type: Error
            example: !include examples/Error.json

7.3. Application

We then apply this trait to our resource types:

resourceTypes:
  collection:
    usage: Use this resourceType to represent any collection of items
    description: A collection of <<"resourcePathName|!uppercamelcase">>
    get:
      description: |
        Get all <<"resourcePathName|!uppercamelcase">>,
        optionally filtered
      is: [ hasResponseCollection: { typeName: <<"typeName">> } ]
    post:
      description: Create a new <<"resourcePathName|!singularize">>
      is: [ hasRequestItem: { typeName: <<"typeName">> } ]
  item:
    usage: Use this resourceType to represent any single item
    description: A single <<"typeName">>
    get:
      description: Get a <<"typeName">>
      is: [ hasResponseItem: { typeName: <<"typeName">> }, hasNotFound ]
    put:
      description: Update a <<quot;typeName">>
      is: | [ hasRequestItem: { typeName: <<quot;typeName">> }, hasResponseItem: { typeName: <<quot;typeName">> }, hasNotFound ]
    delete:
      description: Delete a <<quot;typeName">>
      is: [ hasNotFound ]
      responses:
        204:

We can also apply traits to methods defined within resources. This is especially useful for “one-off” scenarios where a resource-method combination matches one or more traits but does not match any defined resource type:

/foos:
...
  /name/{name}:
    get:
      description: List all foos with a certain name
      is: [ hasResponseCollection: { typeName: Foo } ]

8. 結論

首先，我們識別了資源中的冗餘部分，認識到它們的模式，並提取資源類型。然後我們對在資源中常見的用於提取特性的方法也進行了相同的操作。然後我們能夠通過將特性應用於我們的資源類型以及“一次性”資源方法組合，這些組合沒有嚴格匹配我們定義的資源類型，從而進一步減少冗餘。

以下是 RAML API 的完整內容:

#%RAML 1.0
title: Baeldung Foo REST Services API
version: v1
protocols: [ HTTPS ]
baseUri: http://rest-api.baeldung.com/api/{version}
mediaType: application/json
securedBy: basicAuth
securitySchemes:
  basicAuth:
    description: |
      Each request must contain the headers necessary for
      basic authentication
    type: Basic Authentication
    describedBy:
      headers:
        Authorization:
          description: |
            Used to send the Base64 encoded "username:password"
            credentials
            type: string
      responses:
        401:
          description: |
            Unauthorized. Either the provided username and password
            combination is invalid, or the user is not allowed to
            access the content provided by the requested URL.
types:
  Foo:   !include types/Foo.raml
  Bar:   !include types/Bar.raml
  Error: !include types/Error.raml
resourceTypes:
  collection:
    usage: Use this resourceType to represent a collection of items
    description: A collection of <<resourcePathName|!uppercamelcase>>
    get:
      description: |
        Get all <<resourcePathName|!uppercamelcase>>,
        optionally filtered
      is: [ hasResponseCollection: { typeName: <<typeName>> } ]
    post:
      description: |
        Create a new <<resourcePathName|!uppercamelcase|!singularize>>
      is: [ hasRequestItem: { typeName: <<typeName>> } ]
  item:
    usage: Use this resourceType to represent any single item
    description: A single <<typeName>>
    get:
      description: Get a <<typeName>>
      is: [ hasResponseItem: { typeName: <<typeName>> }, hasNotFound ]
    put:
      description: Update a <<typeName>>
      is: [ hasRequestItem: { typeName: <<typeName>> }, hasResponseItem: { typeName: <<typeName>> }, hasNotFound ]
    delete:
      description: Delete a <<typeName>>
      is: [ hasNotFound ]
      responses:
        204:
traits:
  hasRequestItem:
    body:
      application/json:
        type: <<typeName>>
  hasResponseItem:
    responses:
      200:
        body:
          application/json:
            type: <<typeName>>
  hasResponseCollection:
    responses:
      200:
        body:
          application/json:
            type: <<typeName>>[]
  hasNotFound:
    responses:
      404:
        body:
          application/json:
            type: Error
            example: !include examples/Error.json
/foos:
  type: { collection: { typeName: Foo } }
  get:
    queryParameters:
      name?: string
      ownerName?: string
  /{fooId}:
    type: { item: { typeName: Foo } }
  /name/{name}:
    get:
      description: List all foos with a certain name
      is: [ hasResponseCollection: { typeName: Foo } ]
/bars:
  type: { collection: { typeName: Bar } }
  /{barId}:
    type: { item: { typeName: Bar } }
  /fooId/{fooId}:
    get:
      description: Get all bars for the matching fooId
      is: [ hasResponseCollection: { typeName: Bar } ]

Next »

« Previous

0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.