+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 > > } > > > >
