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