Is the way to exclude property from body type (RAML)?

Question

Is there a way to exclude one or more properties from a request body when you use a type and writing your API using RAML 1.0

I'll explain. I have a type: 'Order' with a set of properties. I have a resource /orders and a method post which allows users to create a new order. The request body is an order struct json and a response is an order struct as well.

But I don't want users to specify order id while they are submitting their request. But that id (and a couple more 'response only' fields) will be returned at the response. I don't want to create an extra type, like OrderRequest and then inherit it with an Order type, maybe there is a more elegant solution?

So I want to have a way to exclude some properties from a request body and keep others in order to use their description and examples.

Thanks and sorry for my English :)

Aldric

Answer 1

Use two types. The second will be child of the first. Example:

#%RAML 1.0
title: GitHub API
version: v3
baseUri: https://api.github.com
mediaType:  application/json
types:
  OrderCreating:
    type: object
    properties:
      products:
        description: List of product ids with amount.
        required: true
        type: object
        properties:
          []:
            type: number
      coupon?: string
  Order:
    type: OrderCreating
    properties:
      id: integer
      price: number
...
/orders:
  post:
    body:
      application/json:
        type: OrderCreating
  /{orderId}:
    get:
      responses:
        200:
          body:
            application/json:
              type: Order

Also you can include Library with declaration of your types.

Crater

Answer 2

As you don't want to create an extra type with inheritance you can still mark the field as optional and document that it is present in the response.

Belting