A Open-API derived JS + Node.js API client for Netlify
A Netlify OpenAPI client that works in the browser and Node.js.
const NetlifyAPI = require('netlify')const listNetlifySites = async function () { const client = new NetlifyAPI('1234myAccessToken') const sites = await client.listSites() return sites }
const NetlifyAPI = require('netlify')const client = new NetlifyAPI('1234myAccessToken')
const listCreateAndDeleteSite = async function () { // Fetch sites const sites = await client.listSites()
// Create a site. Notice
body
here for sending OpenAPI body const site = await client.createSite({ body: { name:my-awesome-site
, // ... https://open-api.netlify.com/#/default/createSite }, })// Delete site. Notice
site_id
is a path parameter https://open-api.netlify.com/#/default/deleteSite await client.deleteSite({ site_id: siteId, }) }
client = new NetlifyAPI([accessToken], [opts])
Create a new instance of the Netlify API client with the provided
accessToken.
accessTokenis optional. Without it, you can't make authorized requests.
optsincludes:
const opts = { userAgent: 'netlify/js-client', scheme: 'https', host: 'api.netlify.com', pathPrefix: '/api/v1', accessToken: '1234myAccessToken', agent: undefined, // e.g. HttpsProxyAgent globalParams: {}, // parameters you want available for every request. // Global params are only sent of the OpenAPI spec specifies the provided params. }
client.accessToken
A setter/getter that returns the
accessTokenthat the client is configured to use. You can set this after the class is instantiated, and all subsequent calls will use the newly set
accessToken.
client.basePath
A getter that returns the formatted base URL of the endpoint the client is configured to use.
The client is dynamically generated from the OpenAPI definition file. Each method is is named after the
operationIdname of each operation. To see a list of available operations, please see the OpenAPI website.
Every OpenAPI operation has the following signature:
response = await client.operationId([params], [opts])
Performs a call to the given endpoint corresponding with the
operationId. Returns a promise resolved with the body of the response, or rejected with an error with the details about the request attached. Rejects if the
status> 400.
paramsis an object that includes any of the required or optional endpoint parameters.
params.bodyshould be an object which gets serialized to JSON automatically. Any object can live here but refer to the OpenAPI specification for allowed fields in a particular request body. It can also be a function returning an object.
binary,
params.bodycan be a Node.js readable stream or a function returning one (e.g.
() => fs.createReadStream('./foo')). Using a function is recommended.
// example params const params = { any_param_needed, paramsCanAlsoBeCamelCase, body: { an: 'arbitrary js object', }, }
Optional
optscan include any property you want passed to
node-fetch. The
headersproperty is merged with some
defaultHeaders.
// example opts const opts = { headers: { // Default headers 'User-agent': 'netlify-js-client', accept: 'application/json', }, // any other properties for node-fetch }
All operations are conveniently consumed with async/await:
const getSomeData = async () => { // Calls may fail! try { return await client.getSiteDeploy({ siteId: '1234abcd', deploy_id: '4567', }) } catch (error) { // handle error } }
If the response includes
jsonin the
contentTypeheader, fetch will deserialize the JSON body. Otherwise the
textof the response is returned.
Some methods have been added in addition to the open API operations that make certain actions simpler to perform.
accessToken = await client.getAccessToken(ticket, [opts])
ticketand get back an
accessToken. Call this with the response from a
client.createTicket({ client_id })call. Automatically sets the
accessTokento
this.accessTokenand returns
accessTokenfor the consumer to save for later.
Optional
optsinclude:
const opts = { poll: 1000, // number of ms to wait between polling timeout: 3.6e6, // number of ms to wait before timing out }
See the authenticating docs for more context.
// example: const open = require('open') // installed with 'npm i open'const login = async () => { const ticket = await client.createTicket({ clientId: CLIENT_ID, }) // Open browser for authentication await open(
https://app.netlify.com/authorize?response_type=ticket&ticket=${ticket.id}
) const accessToken = await client.getAccessToken(ticket) // API is also set up to use the returned access token as a side effect return accessToken // Save this for later so you can quickly set up an authenticated client }
deploy = await client.deploy(siteId, buildDir, [opts])
Node.js only: Pass in a
siteId, a
buildDir(the folder you want to deploy) and an options object to deploy the contents of that folder. Sometimes this method needs to write to a
tmpDir. By default
tmpDiris a folder in the system temporary directory.
The following paths can be passed in the options:
configPath(path to a
netlify.tomlfile that includes redirect rules for the deploy, etc.)
fnDir(a folder with lambda functions to deploy)
Optional
optsinclude:
const opts = { fnDir: null, // path to a folder of functions to deploy branch: null, // branch to pass onto the netlify api configPath: null, // path to a netlify.toml file to include in the deploy (e.g. redirect support for manual deploys) draft: false, // draft deploy or production deploy message: undefined, // a short message to associate with the deploy deployTimeout: 1.2e6, // 20 mins parallelHash: 100, // number of parallel hashing calls parallelUpload: 5, // number of files to upload in parallel maxRetry: 5, // number of times to try on failed file uploads filter: (filepath) => { /* return false to filter a file from the deploy */ }, tmpDir: tempy.directory(), // a temporary directory to zip functions into statusCb: (statusObj) => { // a callback function to receive status events // statusObj: { // type: name-of-step // msg: msg to print // phase: [start, progress, stop] // } // See https://github.com/netlify/cli/blob/v2.0.0-beta.3/src/commands/deploy.js#L161-L195 // for an example of how this can be used. }, // passing a deployId will update an existing deploy based on the provided options deployId: null, }
Node.js only: If this client is used behind a corporate proxy, you can pass an
HttpsProxyAgentor any other
http.Agentthat can handle your situation as
agentoption:
const HttpsProxyAgent = require('https-proxy-agent')const proxyUri = 'http(s)://[user:[email protected]]proxyhost:port' const agent = new HttpsProxyAgent(proxyUri) const client = new NetlifyAPI('1234myAccessToken', { agent })
A UMD build is provided for your convenience, however browser support is still experimental. Contributions to improve browser support are welcome.
See CONTRIBUTING.md for more info on how to make contributions to this project.
MIT. See LICENSE for more details.