Skip to main content

Download the iStreamPlanet CLI

iStreamPlanet's APIs implement OpenAPI 3 descriptions which are publicly linked via RFC 8631 service-desc link relation headers and provide auto-discovery for CLI configuration via the x-cli-config extension. This means you can use any client which understands these features to interact with our APIs.

Installation

We recommend getting started with Restish, a simple cURL-like commandline client for REST-ish APIs. Commands are generated at runtime based on our latest published OpenAPI, so you always have access to the latest API features automatically.

Getting started is easy:

First, make sure you have Homebrew installed. After that, installing or upgrading Restish is a breeze:

# Install Restish
$ brew tap danielgtaylor/restish && brew install restish

# Upgrade Restish to latest release
$ brew upgrade restish

Prefer not to use Homebrew? Then manually download a release.

Configuration

Once installed you need to configure Restish to talk to the iStreamPlanet API. We will use isp as the shorthand name for the iStreamPlanet Streaming APIs. You will be prompted for your organization ID when setting up auth. Once done, select Save and quit.

# Configure Restish to talk to iStreamPlanet.
$ restish api configure isp https://api.istreamplanet.com

? Organization ID [? for help] YOUR_VALUE_HERE
? Select option  [Use arrows to move, type to filter]
  Change base URI (https://api.istreamplanet.com)
  Add profile
  Edit profile default
> Save and exit

Restish supports multiple profiles, which can be set up via the interactive configuration prompt above or by copying & editing in ~/.restish/apis.json. Once configured, you can use -p to reference the profile, for example restish isp -p PROFILE_NAME list-channels.

Example Usage

Commands and help are generated on the fly from the server-provided OpenAPI document. Help commands let you see what is available and how to use it.

# Get a list of all available commands.
$ restish isp --help

# See help for creating/updating a channel.
$ restish isp put-channel --help

Getting Information

Read calls are fairly straightforward and take optional filtering parameters.

# Get a list of sources you have access to.
$ restish isp list-sources

# Get a list of your channels.
$ restish isp list-channels

Lists of items like sources and channels are generally paginated. By default, Restish will make as many requests as needed to get all pages of data before returning. This behavior can be disabled to get a single page, for example:

# Disable auto-pagination, and return up to 5 items from the first page.
$ restish isp list-channels --rsh-no-paginate --page-size=5

Restish is smart about which URIs require authentication by matching them to pre-configured API base URIs, so you can also directly access links you find in responses. For example, you might see something like this returned when listing channels and want to get additional details:

# Get details from a channel by link.
$ restish https://api.istreamplanet.com/v2/channels/my-channel-id

Filtering Data

Restish supports client-side filtering & projection of response data, making it easier to get just the information you need from the API. Filtering uses the -f shorthand function which accepts a JMESPath expression to run against an object that looks like:

{
  "proto": "HTTP/2.0",
  "status": 200,
  "headers": {
    "Header-Name": "header value"
  },
  "links": {
    "link-name": [
      {
        "rel": "link-name",
        "uri": "https://link.url/..."
      }
    ]
  },
  "body": {
    // Body is here
  }
}

Some examples:

# Get just the channel ID and name for all channels:
$ restish isp list-channels -f 'body[].{id, name}'

# Get a raw list of channel IDs that start with "test":
$ restish isp list-channels -f 'body[?starts_with(@.id, `"test"`)]'.id -r

# Get the ETag (content version) of a channel:
$ restish isp get-channel my-channel -f `headers.Etag` -r

# Get all HD encodings for a channel:
$ restish isp get-channel my-channel -f 'body.transcode.video_encoders[?height >= `720`].{id, width, height, bit_rate}'

Note that enabling filtering will also enable JSON output mode.

Writing Data

Write calls take input in one of two ways: JSON passed in via stdin or a custom CLI shorthand syntax on the commandline.

# Pass JSON via stdin.
$ echo '{"name": "My Test Channel", "ingest": {"source": {"id": "s-abc123"}}}' >input.json
$ restish isp put-channel my-channel-id <input.json

# Pass data on the commandline via shorthand.
$ restish isp put-channel my-channel-id name: My Test Channel, ingest.source.id: s-abc123, ...

Read the Restish documentation for more in-depth CLI info and check out our Guide and API reference for examples that show you how to use the iStreamPlanet APIs.