You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficcontrol.apache.org by ocket 8888 <oc...@gmail.com> on 2021/02/08 22:15:58 UTC
TO Go client best practices
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
}
Re: [EXTERNAL] Re: TO Go client best practices
Posted by Matthew Jackson <mj...@alumni.nd.edu>.
+1
On Tue, Feb 9, 2021 at 10:29 AM Rawlin Peters <ra...@apache.org> wrote:
> +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 <mi...@gmail.com>
> wrote:
> >
> > +1
> >
> > On Tue, Feb 9, 2021 at 9:43 AM Chatterjee, Srijeet
> > <SR...@comcast.com.invalid> 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" <zr...@apache.org> 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 <oc...@gmail.com>
> 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
> > > > }
> > > >
> > >
> > >
>
Re: [EXTERNAL] Re: TO Go client best practices
Posted by Rawlin Peters <ra...@apache.org>.
+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 <mi...@gmail.com> wrote:
>
> +1
>
> On Tue, Feb 9, 2021 at 9:43 AM Chatterjee, Srijeet
> <SR...@comcast.com.invalid> 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" <zr...@apache.org> 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 <oc...@gmail.com> 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
> > > }
> > >
> >
> >
Re: [EXTERNAL] Re: TO Go client best practices
Posted by Jeremy Mitchell <mi...@gmail.com>.
+1
On Tue, Feb 9, 2021 at 9:43 AM Chatterjee, Srijeet
<SR...@comcast.com.invalid> 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" <zr...@apache.org> 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 <oc...@gmail.com> 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
> > }
> >
>
>
Re: [EXTERNAL] Re: TO Go client best practices
Posted by "Chatterjee, Srijeet" <SR...@comcast.com.INVALID>.
+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" <zr...@apache.org> 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 <oc...@gmail.com> 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
> }
>
Re: TO Go client best practices
Posted by Zach Hoffman <zr...@apache.org>.
+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 <oc...@gmail.com> 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
> }
>