netlify/js-client
A Netlify OpenAPI client that works in the browser and Node.js.
Usage
const NetlifyAPI = const client = '1234myAccessToken'const sites = await client
Using OpenAPI operations
const NetlifyAPI = const client = '1234myAccessToken' // Fetch sitesconst sites = await client // Create a site. Notice `body` here for sending OpenAPI bodyconst site = await client // Delete site. Notice `site_id` is a path parameter https://open-api.netlify.com/#/default/deleteSiteawait client
API
client = new NetlifyAPI([accessToken], [opts])
Create a new instance of the Netlify API client with the provided accessToken
.
accessToken
is optional. Without it, you can't make authorized requests.
opts
includes:
userAgent: 'netlify/js-client' scheme: 'https' host: 'api.netlify.com' pathPrefix: '/api/v1' accessToken: '1234myAccessToken' 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 accessToken
that 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.
OpenAPI Client methods
The client is dynamically generated from the OpenAPI definition file. Each method is is named after the operationId
name 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.
params
is an object that includes any of the required or optional endpoint parameters.params.body
should 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.- If the endpoint accepts
binary
,params.body
can be a Node.js readable stream or a function returning one (e.g.() => fs.createReadStream('./foo')
). Using a function is recommended.
// example params any_param_needed paramsCanAlsoBeCamelCase body: an: 'arbitrary js object'
Optional opts
can include any property you want passed to node-fetch
. The headers
property is merged with some defaultHeaders
.
// example 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:
{ // Calls may fail! try return await client catch e // handle error }
If the response includes json
in the contentType
header, fetch will deserialize the JSON body. Otherwise the text
of the response is returned.
API Flow Methods
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])
Pass in a ticket
and get back an accessToken
. Call this with the response from a client.createTicket({ client_id })
call. Automatically sets the accessToken
to this.accessToken
and returns accessToken
for the consumer to save for later.
Optional opts
include:
poll: 1000 // number of ms to wait between polling timeout: 36e6 // number of ms to wait before timing out
See the authenticating docs for more context.
// example: { const ticket = await api // Open browser for authentication await const accessToken = await api // 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 tmpDir
is a folder in the system temporary directory.
The following paths can be passed in the options:
configPath
(path to anetlify.toml
file that includes redirect rules for the deploy, etc.)functionsDir
(a folder with lambda functions to deploy)
Optional opts
include:
functionsDir: null // path to a folder of functions to deploy 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: 12e6 // 20 mins parallelHash: 100 // number of parallel hashing calls parallelUpload: 15 // number of files to upload in parallel maxRetry: 5 // number of times to try on failed file uploads { /* return false to filter a file from the deploy */ } tmpDir: tempy // a temporary directory to zip functions into { // 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. }
UMD Builds
A UMD build is provided for your convenience, however browser support is still experimental. Contributions to improve browser support are welcome.
Contributing
See CONTRIBUTING.md for more info on how to make contributions to this project.
License
MIT. See LICENSE for more details.