You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficcontrol.apache.org by "Chatterjee, Srijeet" <SR...@comcast.com.INVALID> on 2021/02/09 16:43:03 UTC
Re: [EXTERNAL] Re: TO Go client best practices
+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 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
> > }
> >
>
>