+1, this will be great to future-proof the client a lot better. - Rawlin
On Tue, Feb 9, 2021 at 10:18 AM Jeremy Mitchell <[email protected]> wrote: > > +1 > > On Tue, Feb 9, 2021 at 9:43 AM Chatterjee, Srijeet > <[email protected]> wrote: > > > +1 > > I did try to reduce the duplicate methods (the ones with the `WithHdr` > > suffix) in `servers` and `server_details` when I wrote the API 4.0 stuff. > > > > --Srijeet > > > > On 2/9/21, 9:30 AM, "Zach Hoffman" <[email protected]> wrote: > > > > +1, this would cut down on a bunch of redundancy that we currently > > have in > > the TO client. > > > > -Zach > > > > On Mon, Feb 8, 2021 at 3:15 PM ocket 8888 <[email protected]> wrote: > > > > > By "best practices" I mean a page in the docs - and probably a > > section in > > > the > > > client README.md - of rules to be followed by authors of new client > > > methods. > > > > > > But that's just a place to put the two practices I'd like to propose > > > putting > > > into place: > > > > > > - All client request methods use one of the call signatures: > > > > > > func (to *Session) MethodName(BodyType, IDType, RequestOptions) > > > (ResponseType, ReqInf, error) > > > func (to *Session) MethodName(BodyType, RequestOptions) > > (ResponseType, > > > ReqInf, error) > > > func (to *Session) MethodName(RequestOptions) (ResponseType, > > ReqInf, > > > error) > > > > > > ... as appropriate, where 'RequestOptions' includes URL query > > string > > > parameters, HTTP headers, and whatever else we decide to add, and > > > 'ResponseType' is the full response from the API (i.e. > > 'response', > > > 'summary' where applicable, and 'alerts'). > > > > > > - The type of the 'Response Body' property of those 'ResponseType's > > should > > > always be a type alias for the client's major version of a > > struct. So > > > you could have, for example > > > > > > type DSV40 struct {...} > > > type DSV4 = DSV40 > > > > > > for API v4.0, but if/when API 4.1 comes out and makes > > (non-breaking) > > > changes to a 'DS', you'd have: > > > > > > type DSV40 struct {...} > > > type DSV41 struct {...} > > > type DSV4 = DSV41 > > > > > > and the APIv4.x client would use 'DSV4' in its call signature's > > > 'ResponseType' so that non-breaking changes could be made to DSes > > > across > > > minor API versions without breaking the client call signature. > > > > > > An example of a full 'ResponseType' from the above call > > signatures, > > > using > > > that 'DSV4' would look like: > > > > > > type DSV4Response struct { > > > // no package qualifier on 'Alerts' because I assume this > > would go > > > in > > > // /lib/go-tc so it's not necessary. > > > Alerts > > > Response DSV4 > > > } > > > > > > >
