Netlify Ruby Client
Netlify is a hosting service for the programmable web. It understands your documents, processes forms and lets you do deploys, manage forms submissions, inject javascript snippets into sites and do intelligent updates of HTML documents through it's API.
The basic flow to using the ruby client is:
- Authenticate (via credentials or a previously aquired access token)
- Get site (via id)
- Deploy
- If site has not been deployed to yet, then the above step will throw a
not found
exception, and you'll need to useNetlify.sites.create
to create the site and do the initial deploy. - If the site has already been deployed and the above step was successful, you can simply use
site.update
to re-deploy.
- If site has not been deployed to yet, then the above step will throw a
If you'd rather, there's also a command line utility to handle most of these steps: Netlify deploy
.
Installation
Install the gem by running
gem install netlify
or put it in a Gemfile and run bundle install
gem netlify
Authenticating
Register a new application at https://app.netlify.com/applications to get your Oauth2 secret and key.
Once you have your credentials you can instantiate a Netlify client.
Netlify = Netlify::Client.new(:client_id => "YOUR_API_KEY", :client_secret => "YOUR_API_SECRET")
Before you can make any requests to the API, you'll need to authenticate with OAuth2. The Netlify client supports two OAuth2 flows.
If you're authenticating on behalf of a user, you'll need to get a valid access token for that user. Use the Netlify client to request an authentication URL:
url = Netlify.(:redirect_uri => "http://www.example.com/callback")
The user then visits that URL and will be prompted to authorize your application to access his Netlify sites. If she grants permission, she'll be redirected back to the redirect_uri
provided in the authorize_url
call. This URL must match the redirect url configured for your Netlify application. Once the user comes back to your app, you'll be able to access a code
query parameter that gives you an authorization code. Use this to finish the OAuth2 flow:
Netlify.(token, :redirect_uri => "http://www.example.com/callback")
If you're not authenticating on behalf of a user you can authorize directly with the API credentials. Just call:
Netlify.
If you already have an OAuth2 access_token
you can instantiate the client like this:
Netlify = Netlify::Client.new(:access_token => access_token)
And the client will be ready to do requests without having to use authorize_from_credentials
. This means that once you've gotten a token via authorize_from_credentials!
you can store it and reuse it for later sessions.
If you're authenticating via the access_token
and you'd like to test if you have a valid access_token
, you can attempt to make a request with the Netlify client and if the token is invalid, a Netlify::Client::AuthenticationError
will be raised. See Miles Matthias' Netlify Rakefile for an example.
Sites
Getting a list of all sites you have access to:
Netlify.sites.each do |site|
puts site.id
puts site.url
end
Each site has a unique, system generated id. Getting a specific site by id:
site = Netlify.sites.get(id)
Creating a site from a directory: (note the path given is a system path)
site = Netlify.sites.create(:dir => "my-site")
puts site.id
You'll want to then save that site id for future reference. Note that a site can also be looked up by its url
.
Creating a site from a zip file:
site = Netlify.sites.create(:zip => "/tmp/my-site.zip")
Both methods will create the site and upload the files to a new deploy.
Creating a site with a dir or a zip is actually a shortcut for this:
site = Netlify.sites.create(:name => "unique-site-subdomain", :custom_domain => "www.example.com")
deploy = site.deploys.create(:dir => "path/to/my-site")
Use wait_for_ready
to wait until a site has finished processing.
site = Netlify.sites.create(:dir => "/tmp/my-site")
site.wait_for_ready
site.state == "ready"
This also works on a specific deploy, and you can pass in a block to execute after each polling action:
deploy = site.deploys.create(:dir => "/tmp/my-site")
deploy.wait_for_ready do |deploy|
puts "Current state: #{deploy.state}"
end
Redeploy a site from a dir:
site = Netlify.sites.get(site_id)
deploy = site.deploys.create(:dir => "/tmp/my-site")
deploy.wait_for_ready
Redeploy a site from a zip file:
site = Netlify.sites.get(site_id)
deploy = site.deploys.create(:zip => "/tmp/my-site.zip")
deploy.wait_for_ready
Update the name of the site (its subdomain), the custom domain and the notification email for form submissions:
site.update(:name => "my-site", :custom_domain => "www.example.com", :notification_email => "[email protected]", :password => "secret-password")
Deleting a site:
site.destroy!
Deploys
Access all deploys for a site
site = Netlify.sites.get(site_id)
site.deploys.all
Access a specific deploy
site = Netlify.sites.get(site_id)
deploy = site.deploys.get(id)
Publish a deploy (makes it the current live version of the site)
site.deploys.get(id).publish
Create a new deploy
deploy = site.deploys.create(:dir => "/tmp/my-site")
Create a draft deploy
deploy = site.deploys.draft(:dir => "/tmp/my-site")
Or
deploy = site.deploys.create(:dir => "/tmp/my-site", :draft => true)
This will upload and process a deploy. You can view the deploy at deploy.deploy_url
and make it the live version of the site with deploy.publish
.
Continuous Deployment
You can also configure continuous deployment for a new or existing site from the Ruby client.
You'll need a Github access token (this will never get sent to Netlify) in addition to your Netlify token. Make sure this access token have the permission to add a deploy key and a web hook to your repository.
Create a new site with continuous deployment:
client.sites.create(:github => {
:repo => "netlify/example",
:dir => "build",
:cmd => "middleman build",
:access_token => GITHUB_ACCESS_TOKEN
})
Configure continuous deployment for an existing site:
site.configure_github!(
:repo => "netlify/example",
:dir => "build",
:cmd => "middleman build",
:access_token => GITHUB_ACCESS_TOKEN
)
Forms
Access all forms you have access to:
Netlify.forms.all
Access forms for a specific site:
site = Netlify.sites.get(id)
site.forms.all
Access a specific form:
form = Netlify.forms.get(id)
Access a list of all form submissions you have access to:
Netlify.submissions.all
Access submissions from a specific site
site = Netlify.sites.get(id)
site.submissions.all
Access submissions from a specific form
form = Netlify.forms.get(id)
form.submissions.all
Get a specific submission
Netlify.submissions.get(id)
Files
Access all files in a site:
site = Netlify.sites.get(id)
site.files.all
Get a specific file:
file = site.files.get(path) # Example paths: "/css/main.css", "/index.html"
Reading a file:
file.read
Snippets
Snippets are small code snippets injected into all HTML pages of a site right before the closing head or body tag. To get all snippets for a site:
site = Netlify.sites.get(id)
site.snippets.all
Get a specific snippet
site.snippets.get(0)
Add a snippet to a site.
You can specify a general
snippet that will be inserted into all pages, and a goal
snippet that will be injected into a page following a successful form submission. Each snippet must have a title. You can optionally set the position of both the general and the goal snippet to head
or footer
to determine if it gets injected into the head tag or at the end of the page.
site.snippets.create(
:general => general_snippet,
:general_position => "footer",
:goal => goal_snippet,
:goal_position => "head",
:title => "My Snippet"
)
Update a snippet
site.snippets.get(id).update(
:general => general_snippet,
:general_position => "footer",
:goal => goal_snippet,
:goal_position => "head",
:title => "My Snippet"
)
Remove a snippet
site.snippet.get(id).destroy
end