OpenAPI v4 Proposal

Re:OpenAPI v4 Proposal by stickfigure on Wednesday May 31, 2023 @06:17PM (#36145150)

I just wish they'd stop using map keys. Use arrays:

    paths:
      - name: "speakers"
        requests:
          - name: createSpeaker
            method: post

This structure would have allowed adding request name to the schema without breaking everything.

This really goes for anyone building REST/JSON APIs. Please avoid dynamic keys; whatever you think the "primary key" is today, it may be different tomorrow. Clients can easily hash an array of objects into a map if they need it.

[ Parent | on HN ]

Re:OpenAPI v4 Proposal by echelon on Wednesday May 31, 2023 @06:29PM (#36145262)

Why not accept map keys as nullable similar to what non-required fields in protobuf do? Wouldn't arrays open you up to duplication?

More broadly, I'm interested in sparse field updates vs. full payload updates and how each of these handle nullable / emptyable fields. I haven't seen any protocol or standard handle these well.

[ Parent | on HN ]

Re:OpenAPI v4 Proposal by withinboredom on Thursday June 01, 2023 @05:09AM (#36148903)

Allow me to introduce you to RFC6902[1]. A standard of how to update without sending the whole thing. There are libraries for almost every language as well.

[1]: https://datatracker.ietf.org/doc/html/rfc6902/

[ Parent | on HN ]

Re:OpenAPI v4 Proposal by handrews on Thursday June 01, 2023 @12:33PM (#36153594)

One of the Moonwalk discussions is indeed about moving from objects to arrays for many structures: https://github.com/OAI/moonwalk/discussions/32

Also, I agree with the person who mentioned JSON Patch (RFC 6902), which I feel is an under-rated and underused technology. While less intuitive than JSON Merge Patch (RFC 7396), it is far more powerful. I have used both together, using JSON Merge Patch where possible to keep things more readable and intuitive, and using JSON Patch where JSON Merge Patch can't do what is needed. Although if most of your changes need JSON Patch, I find it's better to just stick with that.

[ Parent | on HN ]