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
}
