CODEWITHSUNDEEP
restraml
McAbra
McAbra

Reputation: 2524

RAML support for a resource PATCH (RFC 7396)

Problem

I'm trying to describe an API which is supposed to have resources PATCH methods work like described in RFC 7396.
Basically a POST method have a set of properties in it's body, some required some not.
PATCH (by some standards) has no fields required - requests body contains only the fields you want to update, additionally the API allows a client to "clean" a field by sending a null.

Example:

#%RAML 1.0

title: test

mediaType: [application/json]

types:
  Create:
    type: object
    properties:
      description: string
  Retrieve:
    type: Create
    properties:
      id: string
  Update:
    type: object
    properties:
      description?: nil | string


/resource:
  get:
    responses:
      200:
        body:
          type: Retrieve[]
  post:
    body:
      type: Create

  /{id}:
    uriParameters:
      id: string
    get:
      responses:
        200:
          body:
            type: Retrieve
    patch:
      body:
        type: Update
      responses:
        200:
          body:
            type: Retrieve

in the example I have a Update type specified just for that task, because... Create has a required description, Retrieve inherits from Create as it should return all it's fields and the additional id, Update can't inherit from Create as RAML does not allow to override a required field with one that is not required.

Questions:

  1. Is there a better way to describe that API?
  2. If not is nil | string the proper way to go when writing that Update type "from scratch"?

Upvotes: 1

Views: 1754

Answers (1)

Pedro
Pedro

Reputation: 1965

  1. I don't think there's a better way. Only thing is, if you have not required properties in both the create and the update, then you could create a base type.

  2. Yes, nil | [type] is the way to go. You need to be able to "clean" the property by sending null.

Upvotes: 1

Related Questions