Weebly Cloud Client: Ruby

Installation

To install the Weebly cloud client run:

$ gem install weeblycloud

Setup and Authentication

To use the Weebly Cloud client libraries require weeblycloud and configure your API keys.

require weeblycloud

Weeblycloud::CloudClient::configure(API_KEY, API_SECRET)

All future calls will use that API key and secret pairing.

Examples

Creating a user and site, get a login link

begin
	account = Weeblycloud::Account.new
	user = account.create_user("[email protected]")
	site = user.create_site("domain.com", "site_title" => "My Website")
	puts site.login_link()
rescue Weeblycloud::ResponseError => err
	puts "Error: " + err.message
end

Printing the name of all pages in a site matching the query "help"

begin
	pages = site.list_pages("query" => "help")
	pages.each { |page| puts page.get_property("title") }
rescue Weeblycloud::ResponseError => err
	puts "Error: " + err.message
end

Error Handling

If a request is unsuccessful, a ResponseError exception is raised. This can be caught as follows:

begin
	account = Weeblycloud::Account.new
	user = account.create_user("[email protected]")
	site = user.create_site("domain.com", "site_title" => "My Website")
	puts site.login_link()
rescue Weeblycloud::ResponseError => err
	puts err.code # Prints the error code
	puts err.message # Prints the error message
end

If a pagination method is called on a WeeblyCloudResponse that isn't paginated, a PaginationError exception is raised.

Resources

Using and Modifying Resources

• The method resource.get_property(name) of a resource will return the property name of resource. If the property does not exist it will return nil.
• The method resource.set_property(name, value) will set the propety name of resource to value and returns true. If the property does not exist, it will return false. Changes will not be saved until the resource.save() method is called. The Weebly Cloud API does not suppot modifying every resource type nor every property of resource types it supports. For more information, reference the Cloud API Documentation for the resource in question's PUT method.
• The method resource.id() will return the resource ID.
• Use the to_s method to print a JSON representation of the resource's property (i.e. account.to_s). To get the resources properties as a hash, use resource.properties.

Optional parameters

Requests that take serveral optional parameters (i.e. filters or object properties) can have them passed with a options hash.

For instance, to sort all pages by title:

site.list_pages("filterby" => "title", "fitlerfor" => "menu")

And to create a new site:

user.create_site("example.com", 4, "brand_name" => "Brand Name")

Resource Types

Account

API Documentation

• create_user(email, properties={}) Creates a User. Requires the user's email, and optionally accepts keyword arguments of additional properties. Returns a User resource on success.
• get_user(user_id) Return the User with the given ID.
• list_plans() Returns a list of all Plan resources.
• get_plan(plan_id) Return the Plan with the given ID.

User

API Documentation

• enable() Enables a user account after an account has been disabled. Enabling a user account will allow users to log into the editor. When a user is created, their account is automatically enabled.
• disable() Disables a user account. When a user account is disabled, the user will no longer be able to log into the editor. If an attempt to create a login link is made on a disabled account, an error is thrown.
• login_link() Generates a one-time link that will direct users to the editor for the last site that was modified in the account. This method requires that the account is enabled and that the account has at least one site.
• list_themes(filters={}) Returns a list of Theme resources for a given user subject to filters.
• list_sites(filters={}) Returns a list of Site resources for a given user subject to filters.
• get_site(site_id) Return the Site with the given ID.
• create_theme(name, zip_url) Creates a Theme with name name. Requires a zip_url and returns a Theme object.
• create_site(domain) Creates a Site. Requires the site's domain and optionally accepts keyword arguments of additional properties. Returns a Site resource.

Site

API Documentation

• delete() delete the site.
• publish() Publishes the site.
• unpublish() Unpublishes the site.
• login_link() Generates a one-time link that will direct users to the site specified. This method requires that the account is enabled.
• set_publish_credentials(options={}) Sets publish credentials to fields set in keyword arguments. If a user's site will not be hosted by Weebly, publish credentials can be provided. When these values are set, the site will be published to the location specified.
• restore(url) When a site is restored the owner of the site is granted access to it in the exact state it was when it was deleted, including the Weebly plan assigned. Restoring a site does not issue an automatic publish
• disable() Suspends access to the given user's site in the editor by setting the suspended parameter to true. If a user attempts to access the site in the editor, an error is thrown.
• enable() Re-enables a suspended site by setting the suspended parameter to false. Users can access the editor for the site. Sites are enabled by default when created.
• list_pages(filters={}) Returns a list of Page resources for a given site subject to filters.
• list_members(filters={}) Returns a list of Member resources for a given site subject to filters.
• list_groups(filters={}) Returns a list of Group resources for a given site subject to filters.
• list_forms(filters={}) Returns a list of Form resources for a given site subject to filters.
• list_blogs(filters={}) Returns a list of Blog resources for a given site subject to filters.
• get_page(page_id) Return the Page with the given id.
• get_member(member_id) Return the Member with the given id.
• get_group(group_id) Return the Group with the given id.
• get_form(form_id) Return the Form with the given id.
• get_blog(blog_id) Return the Blog with the given id.
• get_plan() Returns the Plan resource for the site.
• set_plan(plan_id, term=None) Sets the site's plan to plan_id with an optional term length. If no term is provided the Weebly Cloud default is used (check API documentation).
• set_theme(theme_id, is_custom) Sets the site's theme to theme_id. Requires a parameter is_custom, distinguishing whether the theme is a Weebly theme or a custom theme.
• create_member(email, name, password, properties={}) Creates a Member. Requires the member's email, name, password, and optionally accepts hash of additional properties. Returns a Member resource.
• create_group(name) Creates a Group. Requires the group's name. Returns a Group resource.

Theme

API Documentation

There are no Theme specific methods.

Blog

API Documentation

• list_blog_posts(filters={}) Returns a list of BlogPost resources for a given blog subject to filters.
• get_blog_post(blog_post_id) Return the BlogPost with the given id.
• create_blog_post(post_body, properties={}) Creates a BlogPost. Requires the post's body and optionally accepts a hash of additional properties. Returns a BlogPost resource.

BlogPost

API Documentation

• delete() delete the blog post.

Form

API Documentation

• list_form_entries(filters={}) Returns a list of FormEntry resources for a given form subject to filters.
• get_form_entry(form_entry_id) Return the FormEntry with the given id.

FormEntry

API Documentation

There are no FormEntry specific methods.

Page

API Documentation

• change_title(title) Changes the title of the page to title. Does not require calling the save() method.

Plan

API Documentation

There are no Plan specific methods.

Group

API Documentation

• delete() Delete the group.

Member

API Documentation

• delete() Delete the Member.

Making Raw API Calls

Not every resource has a cooresponding resource class. It is possible to make a raw API call using a CloudClient object.

client = weeblycloud::CloudClient.new

Using that client, call get, post, put, patch, or delete which takes the endpoint and a hash of optional parameters:

• content: a hash of the request's body.
• params: a hash of query string parameters.
• page (get only): page of results to get
• page_size (get only): page size of results (default is 25)

Request examples

Get cloud admin account account

# Create client
client = weeblycloud::CloudClient.new

# Request the /account endpoint
client.get("account")

Update a page title

# Create client
client = weeblycloud::CloudClient.new

# build endpoint with parameters
endpoint = "user/#{USER_ID}/site/#{SITE_ID}/page/#{PAGE_ID}"

# Make the request
client.patch(endpoint, :content => {"title":"New Title"})

Get all sites for a user (with filters)

# Create client
client = weeblycloud::CloudClient.new

# build endpoint with parameters
endpoint = "/user/#{USER_ID}/site"

# Make the request
client.get(endpoint, :params => {"role":"owner"})

Handling Responses

All requests return a WeeblyCloudResponse object or raise an Exception (see error handling). Accessing the response is easy:

response = client.get("account") # Make a request
puts response.to_s # get the response as a JSON string
# or
puts response.to_hash # get the response as a hash

If the results of a get request are paginated, then response.paginated? will be true.

• response.max_page contains the total number of pages.
• response.current_page contains the current page number.
• response.records is the number of total results.

###Pagination example

client = weeblycloud::WeeblyCloud.new
response = client.get("user/#{USER_ID}/site")

# Print a list of site titles
puts response.map { |site| site['site_title'] }