Unofficial Engines and Languages

If you are looking to utilize RallyHere's environment APIs in a language or engine that we don't have an official integration for, you can still use the APIs directly or by creating a client from our API specification.

OpenAPI Specification File

All RallyHere APIs are defined with an OpenAPI spec defining the endpoints, requests, responses, and the model objects used by them.

The most up-to-date spec file for the environment APIs can be found here. This is generated using the openapi-spec-environment repository.

Generated API Clients

The OpenAPI specification file can be used to generate a language/engine specific implementation of the bare API calls. We recommend OpenAPI Generator for this purpose. All official RallyHere integrations are generated using this tool, and we include any custom generators alongside our integrations. This allows teams to customize the generated client, if necessary.

OpenAPI Generator supports a number of other languages for client generators.

Example OpenAPI Generator Script

The following script can be used to generate a C# client for the RallyHere environment APIs. This script does the following:

1. Downloads OpenAPI Generator CLI
2. Downloads RallyHere Environment API's OpenAPI spec
3. Converts RallyHere Environment API's OpenAPI spec to OpenAPI 3.0.3
4. Generates a C# project using the converted OpenAPI spec

info

OpenAPI Generator does not have full support for OpenAPI 3.1.0 at time of writing. While our spec does make use of a couple of features of 3.1.0 (in particular exclusiveMin/exclusiveMax), we have not experienced issues with this kind of down-converting. If you experience issues, please reach out to your RallyHere representative. There may be other workarounds, or you may need to directly modify the couple of locations using 3.1.0-specific features.

#!/bin/bash
# Copyright 2022-2024 RallyHere Interactive
# SPDX-License-Identifier: Apache-2.0

########################################################################################################################
# Silence some commands that aren't interesting
pushd () {
    command pushd "$@" > /dev/null
}

popd () {
    command popd "$@" > /dev/null
}

########################################
# We only work with this directory structure
DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
pushd $DIR

########################################################################################################################
# Download openapi-generator-cli
curl https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.7.0/openapi-generator-cli-7.7.0.jar --create-dirs -o bin/openapi-generator-cli.jar

########################################################################################################################
# Check if 'java' command is available
if ! command -v java &> /dev/null
then
    echo "Java is not installed. Installing default-jre..."
    sudo apt update
    sudo apt install -y default-jre
fi

########################################################################################################################
# Setup function to run generator once
function generate_csharp_project() {
    PROJECT_NAME=$1
    PACKAGE_GUID=$2
    OPENAPI_SPEC_LOCATION=$3
    rm -rf $PROJECT_NAME
    rm -rf tmp

    # For whatever reason, the csharp generator includes a bunch of stuff that we really don't want - documentation for every class, sln file, etc.
    # So we write to a temporary directory, then move the project out of the temporary directory
    java -cp \
        "bin/openapi-generator-cli.jar" \
        org.openapitools.codegen.OpenAPIGenerator \
        generate \
        -i "$OPENAPI_SPEC_LOCATION" \
        --generator-name="csharp" \
        --output="tmp" \
        --additional-properties="targetFramework=net48,optionalProjectFile=true,packageName=$PROJECT_NAME,packageGuid=$PACKAGE_GUID"

    mv tmp/src/$PROJECT_NAME $PROJECT_NAME
    rm -rf tmp
}

########################################################################################################################
# Download and convert the OpenAPI spec
rm -f rallyhere_env.openapi.json
rm -f rallyhere_env_converted.openapi.json
curl "https://raw.githubusercontent.com/RallyHereInteractive/openapi-spec-environment/main/environment.openapi.json" -o rallyhere_env.openapi.json
jq '
  walk(
    if type == "object" and has("components") then 
      .components.schemas |= with_entries(
        .value |= walk(
          if type == "object" and has("propertyNames") then 
            del(.propertyNames) 
          else . 
          end
        )
      )
    else . 
    end
  ) | 
  .openapi = "3.0.3"
' rallyhere_env.openapi.json > rallyhere_env_converted.openapi.json

########################################################################################################################
# Generate the projects
generate_csharp_project "RallyHereEnvironmentAPI" "DBCB445D-7792-40BB-A3BC-D77D3DBDE99A" "rallyhere_env_converted.openapi.json"

rm -f rallyhere_env_converted.openapi.json

popd