Skip to content

README.md

Latest commit

 

History

History
258 lines (196 loc) · 8.8 KB

README.md

File metadata and controls

258 lines (196 loc) · 8.8 KB
Raw

Ruby API Pack Cloudways

ruby_api_pack_cloudways is a Ruby gem for interacting with the Cloudways API. It provides easy access to providers, server sizes, apps, and packages, with built-in OAuth authentication for secure API requests.

Maintained by PHCDevworks. It is built on ruby_api_pack_core, which supplies its shared HTTP client, response validation, and configuration pattern.

Repository Snapshot

Field Value
Project team project-ruby
Repository role Cloudways API client
Package/artifact ruby_api_pack_cloudways
Current version/status 0.4.0

Standard Workflow

  1. Read AGENTS.md, then the agent-specific guide for the task.
  2. Check TODO.md and ROADMAP.md for current scope.
  3. Make the smallest repo-local change that satisfies the task.
  4. Run bundle exec rspec, bundle exec rubocop, and gem build ruby_api_pack_cloudways.gemspec when validation is required or practical.
  5. Update docs and changelog history only when behavior, public contracts, or release-relevant metadata changed.

Documentation Map

Guide Path
Agent rules AGENTS.md
Claude Code CLAUDE.md
Codex CODEX.md
Copilot COPILOT.md
Jules JULES.md
Roadmap ROADMAP.md
Todo TODO.md
Changelog CHANGELOG.md
Security SECURITY.md
Code of Conduct CODE_OF_CONDUCT.md
Contributing CONTRIBUTING.md

Gem Version CircleCI codecov License

ruby_api_pack_cloudways is a Ruby gem for working with the Cloudways API from Ruby and Rails applications. It centralizes Cloudways credentials, OAuth token fetching, authenticated requests, response parsing, list endpoints, and server operations behind a small service-style API.

Contributing | Code of Conduct | Changelog | Roadmap | Security Policy | AI Guide

Source of Truth

The public behavior of this gem is defined by the configuration object, the Cloudways connection layer, API endpoint wrappers, response validation, and RSpec coverage. Keep those surfaces aligned whenever endpoint behavior changes.

Layer Path Rule
Gem entry point lib/ruby_api_pack_cloudways.rb Loads dependencies and exposes configuration
Configuration lib/ruby_api_pack_cloudways/configuration.rb Owns Cloudways API URL, token path, email, and API key settings
Token handling lib/ruby_api_pack_cloudways/connection/cw_token.rb Fetches and caches Cloudways OAuth access tokens
HTTP connection lib/ruby_api_pack_cloudways/connection/cw_connect.rb Performs authenticated GET and POST requests
List endpoints lib/ruby_api_pack_cloudways/api/cw_lists.rb Public list helpers for Cloudways metadata
Server endpoints lib/ruby_api_pack_cloudways/api/cw_server.rb Public server-management helpers
Response validation lib/ruby_api_pack_cloudways/handlers/response_validator.rb Normalizes expected list responses and logs validation failures
Specs spec/ Contract and regression coverage for configuration, connection, handlers, and API wrappers

After behavior changes, run:

bundle exec rspec
bundle exec rubocop
gem build ruby_api_pack_cloudways.gemspec

What This Gem Owns

  • Cloudways API configuration for Ruby and Rails consumers
  • OAuth token fetching and short-lived token caching
  • Authenticated JSON GET and POST requests through HTTParty
  • Cloudways list helpers for apps, providers, regions, packages, settings, and monitoring metadata
  • Cloudways server helpers for listing, details, lifecycle actions, cloning, scaling, block storage, upgrades, and labels
  • Response validation for list-style Cloudways responses

What This Gem Does Not Own

  • Cloudways account setup, billing, provider availability, or API permissions
  • Host application credential storage
  • Host application authorization policy around server actions
  • UI components, admin dashboards, or deployment workflows
  • Long-running job orchestration around Cloudways operations

Installation

Add the gem to your application's Gemfile:

gem "ruby_api_pack_cloudways"

Install dependencies:

bundle install

Or install it directly:

gem install ruby_api_pack_cloudways

Configuration

Configure the gem before making API calls. In Rails, this usually belongs in an initializer such as config/initializers/ruby_api_pack_cloudways.rb.

RubyApiPackCloudways.configure do |config|
  config.api_url = "https://api.cloudways.com/api/v1"
  config.api_path_token = "/oauth/access_token"
  config.api_email = ENV.fetch("CLOUDWAYS_API_EMAIL")
  config.api_key = ENV.fetch("CLOUDWAYS_API_KEY")
end

Do not commit real Cloudways API keys. Use Rails credentials, environment variables, or your deployment secret manager.

Usage

List Endpoints

List helpers return arrays from Cloudways metadata endpoints.

providers = RubyApiPackCloudways::Api::CwLists.provider_list
sizes = RubyApiPackCloudways::Api::CwLists.server_size_list
apps = RubyApiPackCloudways::Api::CwLists.app_list
packages = RubyApiPackCloudways::Api::CwLists.package_list
regions = RubyApiPackCloudways::Api::CwLists.region_list

Available list helpers:

Method Cloudways resource
app_list Applications
backup_frequency_list Backup frequencies
country_list Countries
monitor_duration_list Monitoring durations
monitor_target_list Monitoring targets
package_list Packages
provider_list Providers
region_list Regions
server_size_list Server sizes
setting_list Settings

Server Endpoints

Server helpers call Cloudways server-management endpoints.

servers = RubyApiPackCloudways::Api::CwServer.server_list
details = RubyApiPackCloudways::Api::CwServer.server_details("123")

RubyApiPackCloudways::Api::CwServer.restart_server("123")
RubyApiPackCloudways::Api::CwServer.update_server_label("123", label: "Production")

Available server helpers:

Method Purpose
server_list List servers
server_details(server_id) Fetch server details
create_server(params) Create a server
clone_server(server_id, params) Clone a server
delete_server(server_id) Delete a server
start_server(server_id) Start a server
stop_server(server_id) Stop a server
restart_server(server_id) Restart a server
disk_usage(server_id) Fetch disk usage
attach_block_storage(server_id, params) Attach block storage
scale_block_storage(server_id, params) Scale block storage
scale_volume_size(server_id, params) Scale volume size
update_server_label(server_id, params) Update a server label
upgrade_server(server_id, params) Upgrade a server

Development

Install dependencies:

bundle install

Run the test suite:

bundle exec rspec

Run style checks:

bundle exec rubocop

Build the gem locally:

gem build ruby_api_pack_cloudways.gemspec

RSpec uses WebMock and VCR. Keep specs isolated from live Cloudways calls unless a maintainer explicitly asks for live API verification.

Documentation and AI Guides

This repository uses the standardized PHCDevworks documentation model adapted from phcdevworks/spectre-tokens and the Rails/Ruby guidance in phcdevworks/phcdevworks_accounts_stytch:

  • AGENTS.md defines shared AI boundaries.
  • CLAUDE.md, CODEX.md, COPILOT.md, and JULES.md define agent-specific working rules.
  • .github/copilot-instructions.md and .github/codex-instructions.md provide GitHub-integrated assistant guidance.
  • CHANGELOG.md, ROADMAP.md, and TODO.md keep release and planning context visible.

Contributing

See CONTRIBUTING.md for setup, coding standards, pull request expectations, and release hygiene.

Security

Please do not report vulnerabilities through public issues. Follow SECURITY.md for responsible disclosure.

License

The gem is available as open source under the terms of the MIT License.