> Can you chat a bit more about the Go API vs HTTP API thoughts?
I don't think any of my thoughts below are specific to Go. I now see that examples in all languages are simply HTTP requests.
I think having a predefined library with, at least, constants (like HTTP header names) and data structures would help having more standardized client code. Perhaps it could even just be a Protobuf definition (there's a hack to use field default values to define constants). Or similar schema language that can easily generate struct definitions/JSON codecs/clients in various languages.
Languages that use camel-case (like Java) often benefit from someone central defining the snake-case/camel-case translation to avoid inconsistencies in the code base. Actually, your examples use snake-case for Rownd-defined fields ("revoke_after,") and camel-case for client-defined fields ("additionalProp1.") Caveat emptor: I might be the only person on Earth who is irked by that. ;)
A layer on top of that would be a client that sets good defaults. For request building, it could populate headers and sanity-check input. For responses, it could convert HTTP responses to exceptions/errors suitable for the programming environment. For failures, it can help defining which error conditions should be retried and back-off settings.
A bonus feature would be to have a fake client (or server) I can use in my unit tests. Something that makes me feel reasonably sure my code will work when talking to your production. That's something I always find more reassuring if the supplier maintains, rather than me.
I don't think any of my thoughts below are specific to Go. I now see that examples in all languages are simply HTTP requests.
I think having a predefined library with, at least, constants (like HTTP header names) and data structures would help having more standardized client code. Perhaps it could even just be a Protobuf definition (there's a hack to use field default values to define constants). Or similar schema language that can easily generate struct definitions/JSON codecs/clients in various languages.
Languages that use camel-case (like Java) often benefit from someone central defining the snake-case/camel-case translation to avoid inconsistencies in the code base. Actually, your examples use snake-case for Rownd-defined fields ("revoke_after,") and camel-case for client-defined fields ("additionalProp1.") Caveat emptor: I might be the only person on Earth who is irked by that. ;)
A layer on top of that would be a client that sets good defaults. For request building, it could populate headers and sanity-check input. For responses, it could convert HTTP responses to exceptions/errors suitable for the programming environment. For failures, it can help defining which error conditions should be retried and back-off settings.
A bonus feature would be to have a fake client (or server) I can use in my unit tests. Something that makes me feel reasonably sure my code will work when talking to your production. That's something I always find more reassuring if the supplier maintains, rather than me.