Crate heroku_rs

heroku_rs

The heroku_rs crate provides convenient Rust bindings for the Heroku V3 API, with a client built on top of Reqwest.

Heroku Client

Creating the Heroku client only takes 1 line. This client takes the API key and has a default 30 second http timeout, default http headers and points to the production Heroku API.

Creating the Heroku Client

use heroku_rs::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
   let api_client = HttpApiClient::create("API_KEY")?;
  
   // You can start making requests here
   
   Ok(())
}

If you want a more customized client, see the client docs

Imports

heroku_rs has two major modules you’ll use most. Endpoints and Framework

You can import both modules by using a global prelude import, which brings everything important into scope.

use heroku_rs::prelude::*;

Or you can import manually what you need if you’re familiar with the crate structure.

e.g. importing space endpoints and the Heroku Client.

use heroku_rs::endpoints::space;
use heroku_rs::framework::apiclient::HerokuApiClient;

API Structure

This crate exposes a module endpoints which gives you access to the specific Heroku endpoints you might need.

Each endpoint on this crate has a unique struct with a consistent naming convention and builder pattern.

- Naming Convention

The convention names are one of these: List, Details, Update, Create, Delete.

The List structs are GET requests, used to return a list of the requested data. E.g. AppList

The Details structs are also GET requests, used to return detailed information about the requested data. E.g. AppDetails

The Create structs are typically POST requests, used to create something on Heroku. E.g. AppCreate

The Update structs are typically PATCH requests, used to update some data on Heroku. E.g. AppUpdate

The Delete structs are typically DELETE requests, used to delete some data on Heroku. E.g. AppDelete

However, there are exceptions to this convention.

If for example we want to rollback a release. Where does that fit in? In this case, the naming matches what we are trying to do. So it’s a ReleaseRollback.

- Builder Pattern

Builder Pattern in this crate is implemented through struct methods.

Anything passed through the builder pattern is a optional parameter and build() method is required to be called in the end, in order to finish the request.

This pattern is implemented this way in order to abstract away some complications and logic from the developer using the crate. They provide a convenient API that is enabled by default but can be disabled.

As mentioned before, each endpoint is implemented as a unique struct. Each struct has it’s own unique struct methods which can be chained as builder methods.

One method that is consistent on every endpoint is the new(...) struct method. This method takes the minimal parameters needed but required to make a successful request to Heroku. That could mean no parameters or many parameters, depending on the endpoint’s requirements.

Example 1: Requesting a list of apps from Heroku.

This request returns a list of Apps, if successful.

use heroku_rs::prelude::*;

let response = api_client.request(&AppList::new());

match response {
    Ok(success) => println!("Success: {:#?}", success),
    Err(e) => println!("Error: {}", e),
}

Example 2: Creating a new app.

As mentioned previously, struct methods are used to provide a more convenient API.

In this case new() takes no parameters, because there are no required parameters needed to pass to Heroku.

However, there are three optional parameters we can pass to Heroku if we want to, and we can do that easily through the builder pattern. See another example

use heroku_rs::prelude::*;

let response = api_client.request(&AppCreate::new());

match response {
    Ok(success) => println!("Success: {:#?}", success),
    Err(e) => println!("Error: {}", e),
}

Example 3: Updating the app.

Now that we created the app in the previous example, we can update it, if we want to.

In this example, we’ll be setting the name “FOO” to it.

This endpoint has one (1) required parameter and that is the unique app identifier or app_id.

This is needed for the crate to know which app it will be updating.

This endpoint also has three optional parameters, build_stack, maintenance and name. We’ll only update the name for now.

Notice how we need to call build() on AppUpdate. That’s because we are using the builder pattern, in this case name("FOO") to update the app name. So we use build() to consume the builder.

use heroku_rs::prelude::*;

let response = api_client.request(&AppUpdate::new("APP_ID").name("FOO").build());

match response {
    Ok(success) => println!("Success: {:#?}", success),
    Err(e) => println!("Error: {}", e),
}

Example 4: Deleting the app.

Last but not least, we can also delete the app. This has one (1) required parameter, which is the app_id of the App we want to delete.

use heroku_rs::prelude::*;

let response = api_client.request(&AppDelete::new("FOO"));

match response {
    Ok(success) => println!("Success: {:#?}", success),
    Err(e) => println!("Error: {}", e),
}

Additional examples:

• Heroku_rs repository examples

Modules

endpoints	Module for the available endpoints on the crate.
framework	Module for for authentication, api clients and response parsing.
macros
prelude	A module meant to be glob imported when using heroku_rs.

Macros

heroku_env