4

If we look at a message API (for example) I want it to be able to

  • create a message
  • get a message
  • update a message

A message contains an external reference (a unique id from the consumer)

  • This external_id should be set at creation with a POST request
  • This external_id, could not be changed with a PATCH

What is the solution to implement it?

An API sample:

swagger: '2.0'

host: api.com
basePath: /v2
schemes:
  - https

info:
  title: dummy
  version: 1.0.0

consumes:
  - application/json

produces:
  - application/json


paths:
  /messages:
    post:
      summary: Create a message
      parameters:
        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'


  /messages/{id}:
    get:

      summary: "Get a message by ID"
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

      responses:

        200:
          description: OK - the message
          schema:
            $ref: '#/definitions/Message'

    patch:
      summary: Modify a message
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'

definitions:

  Message:
    type: object
    required:
      - id
      - external_id
      - title
      - content
      - created_at

    properties:
      id:
        type: string
        readOnly: true

      external_id:
        type: string
        description: "Your own reference ID"

      title:
        type: string

      content:
        type: string

      created_at:
        type: string
        format: date-time
        readOnly: true

The only solutions I see:

  • defining 2 definitions (Message and UpdatedMessage) using allOf
  • not using the definition in the PATCH method or in the GET/POST method

Is there a better solution to achieve this? The ideal solution would be to have only one Message definition, and in the PATCH method, to override the Message definition (removing the field).

I don't know if it is possible.

Thx

1 Answer 1

1

To handle this use case, you must define 2 messages:

  • An UpdateMessage containing all properties except external_id
  • A Message containing all UpdateMessage properties plus external_id using allOf is the only way of achieving this with OpenAPI (fka. Swagger) 2.0 version.

Here's the corresponding YAML:

swagger: '2.0'

host: api.com
basePath: /v2
schemes:
  - https

info:
  title: dummy
  version: 1.0.0

consumes:
  - application/json

produces:
  - application/json


paths:
  /messages:
    post:
      summary: Create a message
      parameters:
        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/Message'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'


  /messages/{id}:
    get:

      summary: "Get a message by ID"
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

      responses:

        200:
          description: OK - the message
          schema:
            $ref: '#/definitions/Message'

    patch:
      summary: Modify a message
      parameters:
        - name: id
          in: path
          description: The message ID
          required: true
          type: string
          format: uuid

        - name: message
          in: body
          required: true
          schema:
            $ref: '#/definitions/UpdateMessage'

      responses:

        201:
          description: Ok
          schema:
            $ref: '#/definitions/Message'

definitions:

  UpdateMessage:
    type: object
    required:
      - id
      - title
      - content
      - created_at

    properties:
      id:
        type: string
        readOnly: true

      title:
        type: string

      content:
        type: string

      created_at:
        type: string
        format: date-time
        readOnly: true

  Message:
    allOf:
      - $ref: '#/definitions/UpdateMessage'
      - required:
          - external_id
        properties:
          external_id:
            type: string
            description: "Your own reference ID"

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.