Schema for responses (or nesting schemas)

Hi there! I’m learning RAML 1.0 as part of a Mulesoft implementation, and I have a question about reusing code by creating a schema for the responses.

For this example:

  1. The API supports GET and POST, and they’re identical except for the description.
  2. The API resources either take 2 parameters or none.

I want to reuse the code as much as possible, so I’m trying to do something along these lines:

#%RAML 1.0
title: Test API
mediaType: [ application/json ]

resourceTypes:
  myResp:
    200:
      body:
        application/json:
          example: { "message": "OK" }
    400:
      body:
        application/json:
          example: { "message": "FAIL" }
  hasParams:
    get:
      queryParameters:
        param1:
          type: boolean
        param2:
          type: boolean
      responses:
        type: myResp
    post:
      queryParameters:
        param1:
          type: boolean
        param2:
          type: boolean
      responses:
        type: myResp
  noParams:
    get:
      responses:
        type: myResp
    post:
      responses:
        type: myResp


/dog:
  type: hasParams
  get:
    description: Doggo fetch
  post:
    description: Doggo hide
/cat:
  type: noParams
  get:
    description: Catto eat
  post:
    description: Catto un-eat

However, I’m getting a syntax error on “type: myResp” saying that the response isn’t found. I’m guessing it’s trying to literally interpret “myResp” as a HTTP code instead of using the myResp schema.

What’s the best way to do this, and does the rest of the RAML look valid?

Additionally, is there anywhere else I could increase code re-use here (ideally without using includes)? For instance, is there a way to schematize the repetitive content under “post:” and “get:”?

Thanks in advance for your help!

The issue is that you’re trying to apply a resourceType on a response. You can read more on how to apply resourceTypes here.

There are many ways you could go about this.

One way would be to externalize the content of myResp to a separate YAML file and !include that file wherever you need it. You can read more about includes here.

Another way would be to use traits. This is what it would look like re-using your example above:

#%RAML 1.0
title: Test API
mediaType: [ application/json ]

traits:
  myResp:
    responses:
      200:
        body:
          application/json:
            example: { "message": "OK" }
      400:
        body:
          application/json:
            example: { "message": "FAIL" }

resourceTypes:
  hasParams:
    get:
      is: [ myResp ]
      queryParameters:
        param1:
          type: boolean
        param2:
          type: boolean
    post:
      is: [ myResp ]
      queryParameters:
        param1:
          type: boolean
        param2:
          type: boolean
  noParams:
    get:
      is: [ myResp ]
    post:
      is: [ myResp ]

/dog:
  type: hasParams
  get:
    description: Doggo fetch
  post:
    description: Doggo hide
/cat:
  type: noParams
  get:
    description: Catto eat
  post:
    description: Catto un-eat
1 Like

Thanks a ton for the response! That is extremely helpful. Traits are exactly what I’m looking for. :grin: