Heroku Platform API SDKs & Libraries: Official & Community Tools

SDKs overview

The Heroku Platform API provides a programmatic interface for managing Heroku applications, resources, and add-ons. Software Development Kits (SDKs) and libraries simplify interaction with this API by abstracting HTTP requests and responses into language-specific objects and methods. These tools enable developers to automate tasks such as creating applications, deploying code, scaling dynos, and managing databases, integrating Heroku's Platform as a Service (PaaS) capabilities directly into their development workflows and custom applications. While Heroku primarily offers a robust Command Line Interface (CLI) as its official tool for API interaction, a vibrant community contributes various language-specific libraries.

The Heroku Platform API is a RESTful API, meaning it adheres to architectural principles that define how web services communicate, using standard HTTP methods like GET, POST, PUT, and DELETE to perform operations on resources. This design allows for flexibility in how clients interact with the API, supporting a wide range of programming languages and environments. For detailed information on the API's endpoints and data models, refer to the Heroku Platform API reference documentation.

Official SDKs by language

Heroku's primary official tool for interacting with the Platform API is the Heroku CLI. While not a traditional language-specific SDK in the same vein as a client library for a specific programming language, the CLI provides a comprehensive interface for managing all aspects of Heroku applications. It is built on top of the Platform API and offers a command-line abstraction that is highly scriptable and integrates seamlessly into developer toolchains. The Heroku CLI supports various operating systems and provides a consistent experience across different development environments.

The Heroku CLI is actively maintained and is the recommended method for programmatic interaction with the Heroku Platform API for most use cases. Its capabilities extend to managing applications, add-ons, databases, domains, and more, all accessible through a unified command-line interface. Developers can also use the Heroku CLI to execute custom scripts that automate deployment pipelines or integrate with continuous integration/continuous delivery (CI/CD) systems. For a complete guide on installing and using the Heroku CLI, consult the Heroku CLI documentation.

Installation

The Heroku CLI is the primary tool for interacting with the Heroku Platform API. Its installation process varies slightly depending on your operating system and preferred package manager. Below are common installation methods:

macOS

For macOS users, Homebrew is the recommended package manager for installing the Heroku CLI:

brew tap heroku/brew
brew install heroku

Windows

On Windows, you can use the standalone installer or Chocolatey package manager:

Standalone Installer

Download and run the installer from the Heroku Dev Center.

Chocolatey

choco install heroku

Linux

For Linux distributions, the recommended method involves using Snap or a direct installation script:

Snap (Ubuntu, Linux Mint, Fedora, Debian, etc.)

sudo snap install --classic heroku

Debian/Ubuntu

curl https://cli-assets.heroku.com/install.sh | sh

Verification

After installation, verify that the Heroku CLI is correctly installed by checking its version:

heroku --version

This command should output the installed version of the Heroku CLI, confirming a successful installation. Once installed, you will need to log in to your Heroku account using heroku login to authenticate and begin interacting with your applications.

Quickstart example

This quickstart example demonstrates how to use the Heroku CLI to create a new application, deploy a sample Node.js application, and open it in a web browser. This process illustrates the core workflow of interacting with the Heroku Platform API through the CLI.

Prerequisites

• Heroku CLI installed and authenticated (heroku login).
• Git installed.
• A sample Node.js application (or any other supported language) with a Procfile and a package.json (for Node.js) or equivalent build configuration. For this example, we'll assume a simple Node.js app that serves "Hello, Heroku!" on port $PORT.

Sample Node.js Application (server.js)

const express = require('express');
const app = express();
const port = process.env.PORT || 3000;

app.get('/', (req, res) => {
  res.send('Hello, Heroku!');
});

app.listen(port, () => {
  console.log(`App listening at http://localhost:${port}`);
});

package.json

{
  "name": "heroku-quickstart-app",
  "version": "1.0.0",
  "description": "A simple Node.js app for Heroku quickstart",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "engines": {
    "node": "16.x"
  }
}

Procfile

web: node server.js

Steps

1. Create a new directory and initialize Git:

   mkdir heroku-quickstart-app
   cd heroku-quickstart-app
   git init

2. Create the sample application files:

   Place the server.js, package.json, and Procfile content into their respective files within the heroku-quickstart-app directory.

3. Add and commit your code:

   git add .
   git commit -m "Initial commit for Heroku quickstart app"

4. Create a Heroku application:

   heroku create

   This command creates a new application on Heroku, assigns it a unique name (e.g., flowing-river-12345), and adds a Git remote named heroku to your local repository. The output will include the URL of your new Heroku application.

5. Deploy your application:

   git push heroku main

   This command pushes your local main branch to the heroku remote, triggering a build and deployment process on Heroku. Heroku automatically detects the Node.js application, installs dependencies, and starts the web process defined in your Procfile. The deployment logs will be displayed in your terminal.

6. Open the application in your browser:

   heroku open

   This command opens your deployed Heroku application in your default web browser, allowing you to see "Hello, Heroku!" served by your application.

7. View application logs (optional):

   heroku logs --tail

   This command displays a real-time stream of your application's logs, useful for debugging and monitoring.

This quickstart demonstrates the fundamental steps of using the Heroku CLI to manage the application lifecycle, from creation to deployment and access. For more advanced configurations and features, refer to the Heroku Getting Started with Node.js guide.

Community libraries

Beyond the official Heroku CLI, the developer community has created various libraries and wrappers for interacting with the Heroku Platform API in different programming languages. These libraries often provide a more idiomatic way to interact with the API within a specific language ecosystem, turning raw API calls into familiar object-oriented or functional programming constructs.

Ruby

• Platform API Ruby Client: A popular community-maintained Ruby client library for the Heroku Platform API. It provides a convenient Ruby interface for all API endpoints. Installation is typically via RubyGems: gem install platform-api. For usage details, developers can refer to its GitHub repository.

Python

• heroku.py: A Python wrapper for the Heroku API. This library aims to provide a simple and Pythonic way to interact with Heroku. It can be installed using pip: pip install heroku.py. The project's GitHub page contains documentation and examples.

Node.js

• node-heroku-client: A Node.js client for the Heroku Platform API. This library helps Node.js developers interact with Heroku services from their applications or scripts. Installation is via npm: npm install heroku-client. Developers can find more information and examples on its GitHub repository.

Other Languages

While the above are some of the more established community libraries, developers can find additional tools by searching package repositories (e.g., Maven Central for Java, Packagist for PHP, Go Modules for Go) or GitHub for "Heroku API client" in their preferred language. When choosing a community library, it is advisable to consider its maintenance status, community support, and alignment with the latest Heroku Platform API features. For general guidance on choosing and evaluating third-party libraries, resources like the MDN Web Docs on JavaScript modules offer insights into dependency management, which can be generalized to other language ecosystems.