Build: How to name Netlify API client instances?

[ehmicky]

Following from our discussion with @verythorough @DavidWells @tzmanics @Benaiah @toddmorey, we were wondering about the variable name to use when describing Netlify API client instances, in our documentation and in the plugin shape. At the moment we use netlify, api or client. What are your thoughts?

[DavidWells]

This feature unfortunately won't be ready until API changes are made in the core Netlify API

As such, we should not document or expose this feature at this time.

It will work locally but break in CI 😢

Need to pause this feature until https://github.com/netlify/bitballoon/issues/4980 is resolved

[ehmicky]

I have just added #585 for hiding the API client feature from the documentation and plugin arguments.

We can still discuss this issue even though the feature is momentarily paused. Also this discussion is broader than this specific feature (for example it applies to the js-client documentation as well).

[ehmicky]

Which name do you think would fit best variables holding the netlify client?

• api
• client
• netlifyClient
• apiClient
• netlify
• others?

[DavidWells]

Curious to hear what others think. @jlengstorf @philhawksworth @sdras @tzmanics @shortdiv @sw-yx

For context, this is referencing the api value passed in here:

Is api clear or would another suggestion above make more sense?

[philhawksworth]

Part of me likes the idea of it being called netlify since it is the API to interact with the Netlify sdk. But I think that might lead us to a place where the word is a bit overloaded and confusion might creep in.

Calling it api and documenting it as you have seems logical to me.

(And I appreciate seeing this level of detail being exposed, BTW. Knowing that any plugin could access these things at any lifecycle stage, and that this signature will be consistent is great!)

[jlengstorf]

would it make sense to put this under utils — it kind of feels like the same thing?

utils.api or utils.sdk or something similar

maybe I'm missing some context, but is there a reason to add another top-level property?

[ehmicky]

Yes @jlengstorf I think you're right, this should live under utils.api.
@DavidWells what do you think?

[DavidWells]

Not sure on this one yet. We have time to figure it out while waiting on https://github.com/netlify/bitballoon/issues/4980

[tzmanics]

i'm ok with api or utils.api or netlifyApi to make it more specific. i actually don't like the idea of adding client anywhere in there bc i think it might muddle what it is even more. it's the 'API instance of the Netlify SDK' then we add client around there somewhere, it may get a little confusing.

[ehmicky]

I believe the buildbot support is almost fixed now: https://github.com/netlify/buildbot/pull/596

Can we re-enable the API client in Build plugins under utils.api? The code is already there and is tested, I just need to remove a feature flag.

@DavidWells @erquhart

[DavidWells]

We are going to need to push this feature back until we can get a token with more permissions.

Keep it out for now.

We need to use that token for the build cancellation stuff

[vbrown608]

@DavidWells this will be granted by https://github.com/netlify/buildbot/pull/596

[ehmicky]

Thanks a lot @vbrown608!

@DavidWells Does https://github.com/netlify/buildbot/pull/596 fix the problem?

[mraerino]

i'd like to use this feature in order to easily prototype the edge functions deployment, so i don't have to do heavy work on buildbot.
I'd like to get access to the raw token as well, so i can make my own api requests.

I can take care of sorting out permissions for that in bitballoon.

What is blocking this?

[ehmicky]

One thing we could do is passing to plugin event handlers either:

• only the token string as utils.api
• both utils.api.client (js-client instance) and utils.api.token (string)

One concern with passing the js-client instance is that its version won't be pinned to a specific major release (as opposed to letting users require it).

Another concern would be security. We could:

• scope the token to the duration build (we already do this)
• ensure only Build plugins can access it, not build.command:
  
  
  
  • in particular, we currently used CLI flags. As demonstrated by @mraerino, this is not safe.
  
  
  • we could instead pass it via environment variable: TOKEN=... @netlify/build ..., then remove that environment variable from child processes environment (build.command and Build plugins)
  
  
• scope the token to specific endpoints. Probably only read-only ones?

[erquhart]

Let's close this ticket regarding the naming decision as utils.api seems amenable to all. Opening a separate issue, will close and link.