Question

我正在构建第一个用于实践和学习的RESTful API。我正在使用RAML，并将通过MuleSofts AnypointStudio来实现。我真的不知道如何处理响应，尤其是错误响应。我设法弄清楚我想要响应的HTTP状态代码，但没弄清楚如何处理响应消息。

我是否需要为每个响应代码（200、201、204、404等）定义响应数据类型和示例消息？如果我可以使用一种数据类型和一种示例消息，该如何相应地使用它们？

目前，我已经定义了一种错误类型和一种示例消息。

Error.raml

#%RAML 1.0 DataType
type: object
description: This general error structure is used throughout this API.
properties:
  code:
    type: integer
    minimum: 400
    maximum: 599
  description?:
    type: string
    default: "Bad query parameter [$size]: Invalid integer value [abc]"
    example: The server understood the request, but is refusing to fulfill it
  reasonPhrase?:
    type: string
    examples:
      example: Bad Request
      example1: Forbidden
example: !include ../examples/error_example.json

error_example.json

{
  "code": 400,
  "description": "Bad query parameter [$size]: Invalid integer value [abc]",
  "reasonPhrase": "Bad Request"
}

如您所见，我在数据类型和示例消息中都有变量。它们由Restlet生成。我还不知道如何利用它们，所以我暂时只剩下它们了。

非常感谢您的帮助和提示。

Answer 1

我是否需要为每个响应代码（200、201、204、404等）定义响应数据类型和示例消息？如果我可以使用一种数据类型和一种示例消息，该如何相应地使用它们？

不，你不知道。对于资源，您可以指定诸如200或404（这些是最常用的）之类的响应

从文档中

resourceTypes:
  collection:
    description: Collection of available songs in Jukebox
    get:
      description: Get a list of songs based on the song title.
      responses:
        200:
          body:
            application/json:
    post:
      description: |
        Add a new song to Jukebox.
      queryParameters:
        access_token:
          description: "The access token provided by the authentication application"
          example: AABBCCDD 
          required: true
          type: string
      body:
        application/json:
          type: song
      responses:
        200:
          body:
            application/json:
              example: |
                { "message": "The song has been properly entered" }

未发现错误的资源示例：

collection-item:
  description: Entity representing a <<resourcePathName|!singularize>>
  get:
    description: |
      Get the <<resourcePathName|!singularize>>
      with <<resourcePathName|!singularize>>Id =
      {<<resourcePathName|!singularize>>Id}
    responses:
      200:
        body:
          application/json:
      404:
        body:
          application/json:
            example: |
              {"message": "<<resourcePathName|!singularize>> not found" }

有一个很好的blog post。看看RAML tutorials，因为他们有不错的文档。您也可以看看Swagger以获得更多的“灵感”。

如何在RESTful API设计中处理错误数据类型和响应消息

1 个答案: