Documentation (2024.2 Enterprise)

# Getting started with the REST API

This tutorial will take you through the development of a command line Helix TeamHub client for managing version control repositories. We hope to show you how everything in TeamHub can be accessed through our RESTful APIs, using plain HTTPS calls with JSON payloads.

The tool will be implemented in Ruby. We are working on making tutorials available for other programming languages. In the meantime, we hope you'll be able to follow along even if you're working in some other language.

## The Tool

The tool we're building can be used for managing source code repositories: Listing them, creating them, or destroying them.

Listing all repositories of a project

    repo list my_project

Creating a repository in a project:

    repo create my_project a_repo git

Deleting a repository from a project

    repo delete my_project a_repo

## Prerequisites

The tutorial is written assuming a Unix based operating system, such as Linux or macOS. However, there is nothing inherently Unix dependent here, so you should be able to apply the tutorial on Windows as well.

You will need to have Ruby 1.9 or later installed. Follow the official installation documentation to get Ruby up and running on your machine.

We'll be using two Ruby gems to help with the lower level details:

- rest-client for making HTTP(S) calls to the API
- json for JSON parsing and serialization

You can get these installed with the `gem` command once you have Ruby installed:

    gem install rest-client json --no-rdoc --no-ri

Depending on how you installed Ruby you may need to use `sudo` to install Gems.

## Set Up The TeamHub Endpoint URL

To make the rest of our work easier, let's put the base URL of the TeamHub API to an environment variable.

If you are using the TeamHub Cloud, this URL is `https://helixteamhub.cloud/api`. If you are using an on-premises installation, replace `helixteamhub.com` with the hostname or IP of your internal TeamHub instance.

Set up an environment variable `HTH_ENDPOINT` with this value. The best way to do this depends on your operating system and shell. For example, on macOS and most Linux installations you can put the following line in `~/.bash_profile`:

    export HTH_ENDPOINT="https://helixteamhub.cloud/api"

## Set Up Keys

In order to access TeamHub from tools such as this one, we need two keys. They allow for fine-grained access control, and for making sure whoever's running the tool has the permission to execute the action under question.

We are going to put all keys into environment variables so that the script – as well as any other scripts you want to develop – is easy to run.

### The Company And Account Keys

The Company Key identifies which company within TeamHub we are dealing with. Most people will only ever have access to a single company's data, but this is not always the case. Because every company in TeamHub has it's own "universe" with unique user and project identifiers, we need to use the Company Key to scope each request to a specific company.

The Account Key identifies who exactly is accessing TeamHub (or on whose behalf we're doing it). Each TeamHub user and bot has a unique account key.

A convenient way to acquire both of these keys is to make an authentication request to the TeamHub API. What you need for it is your TeamHub access credentials (company, login (email or user ID) and password). Run the following command, replacing your own company, login and password (as well as the TeamHub URL if you have an on-premises installation):

    curl -X POST \
      -H "Content-Type: application/json" \
      -H "Accept: application/vnd.hth.v1" \
      -d '{"company": "YOUR COMPANY ID", "login": "YOUR LOGIN", "password": "YOUR PASSWORD" }' \
      https://helixteamhub.cloud/api/account/sessions

The command should print out the JSON response returned by TeamHub. Included in it are the keys for the company and the account. Put the values of those to environment variables:

    export HTH_COMPANY_KEY=value of company_key
    export HTH_ACCOUNT_KEY=value of account_key

## Implement The Script Structure

Now we are ready to start coding our tool. We are going to put everything to a single executable Ruby file. It is a good idea to put it somewhere in your `PATH` so that it's easy to execute. Assuming you have a directory `~/bin` for this purpose, let's create the script there and make it executable:

    touch ~/bin/repo
    chmod +x ~/bin/repo

Next, open the newly created file in your favorite Ruby or text editor. At this point we'll add in everything except the actual TeamHub API calls. Set the file's contents as follows (we will be going through them step by step in a moment):

    #!/usr/bin/env ruby

    require 'rest_client'
    require 'json'

    module HelixTeamHub
      class Client

        def initialize(endpoint, account_key, company_key)
          @endpoint    = endpoint
          @account_key = account_key
          @company_key = company_key
        end

        def list_repos(project_id)
          raise "No project given"         if project_id.nil?

        end

        def create_repo(project_id, repo_id, repo_type)
          raise "No project given"         if project_id.nil?
          raise "No repository given"      if repo_id.nil?
          raise "No repository type given" if repo_type.nil?
          raise "Invalid repository type"  unless %w(git mercurial subversion).include?(repo_type)

        end

        def delete_repo(project_id, repo_id)
          raise "No project given"         if project_id.nil?
          raise "No repository gien"       if repo_id.nil?

        end

      end
    end

    command, project_id, repo_id, repo_type = ARGV

    client = HelixTeamHub::Client.new(ENV['HTH_ENDPOINT'],
                               ENV['HTH_ACCOUNT_KEY'],
                               ENV['HTH_COMPANY_KEY'])

    case command
    when 'list'   then client.list_repos(project_id)
    when 'create' then client.create_repo(project_id, repo_id, repo_type)
    when 'delete' then client.delete_repo(project_id, repo_id)
    else               puts "Unknown command: #{command}"
    end

- On line 1 we define the shebang, letting the shell know it should use Ruby to run this script.
- On lines 3-4 we require the Ruby gems we need for the API calls.
- On lines 5-6 we begin a Ruby class definition for a Helix TeamHub client class we'll be using later in the script: `HelixTeamHub::Client`.
- On lines 9-14 we define the class constructor, which takes the Helix TeamHub API endpoint and the two keys. It stores everything as instance variables.
- On lines 16-19 we define a method for listing the repositories of a project. It takes the project identifier as an argument, and validates that it is not `nil`.
- On lines 21-27 we define a method for creating a repository to a project. It takes the project identifier, the repository identifier, and the reposioty type as arguments. It validates that each of the arguments is present, and that the repository type is one of `git`, `mercurial`, or `subversion`.
- On lines 29-33 we define a method for deleting a repository from a project. It takes the project identifier and the repository identifier as arguments, and validates that both of them are present.
- On lines 35-36 we close the `HelixTeamHub::Client` class definition
- On line 38 we grab the four command line arguments that may have been given to the script: The command to execute, the project identifier in question, the repository identifier, and the repository type. Not all commands need all of these arguments, in which case their value will be `nil`.
- On lines 40-43 we create an instance of the `HelixTeamHub::Client` class. To its constructor we pass the Helix TeamHub endpoint URL and the two keys, which we get from the environment variables we set up earlier.
- On lines 45-50 we finally execute the command that was given, by calling the matching method from the `HelixTeamHub::Client` object. An error message is printed if we can't recognize the command.

## Implement The List Command

To get a list of repositories, we can call the TeamHub API operation `GET /projects/:project_id/repositories`. Let's do exactly that, using the rest-client library we have installed as a Gem and required. Update the `list_repos` method so that it looks like this:

        def list_repos(project_id)
          raise "No project given"         if project_id.nil?

          response = RestClient.get "#{@endpoint}/projects/#{project_id}/repositories",
                                    authorization: auth_header(),
                                    accept: :json
          JSON.parse(response)["results"].each do repo
            print_repo(repo)
          end
        end

- On lines 4-6 we make a GET request to the repositories URL, based on the configured TeamHub API endpoint. We include two HTTP headers: `Authorization` for letting TeamHub know who we are, and `Accept` for letting TeamHub know we want back JSON data.
- On lines 7-9 we parse the returned JSON data to a Ruby data structure, and then iterate over the results (assuming it is an array of repositories). The information of each repository is printed out.

In this code we used two helper methods we haven't defined yet: `auth_header` for defining the contents of the `Authorization` header, and `print_repo` for printing out the information for a repository. Let's define those now.

Within the class definition for `HelixTeamHub::Client`, add two more private methods:

        def auth_header
          %(hth.company_key="#{@company_key}",account_key="#{@account_key}")
        end

        def print_repo(repo)
          puts repo["id"]
          puts "=" * 20
          puts "Type:         #{repo["type"]}"
          puts "SSH access:   #{repo["ssh_url"]}"
          puts "HTTP(s) access: #{repo["http_url"]}"
          puts
        end

- On lines 1-3 we define the `auth_header` method. It constructs a value for the `Authorization` header that TeamHub recognizes. The value begins with the string `hth`, which is followed by the two API keys.
- On lines 5-12 we define a method for printing out a repository. It prints the repository identifier, the type of the repository, and the access URLs for the SSH and HTTPS protocols.

## Implement The Create Command

When creating a repository, we invoke the same endpoint as for listing repositories, but this time we use the POST method instead of GET: `POST /projects/:project_id/repositories`. This time we also provide a JSON payload with the information for the new repository.

Update the `create_repo` method so that it looks like this:

        def create_repo(project_id, repo_id, repo_type)
          raise "No project given"         if project_id.nil?
          raise "No repository given"      if repo_id.nil?
          raise "No repository type given" if repo_type.nil?
          raise "Invalid repository type"  unless %w(git mercurial subversion).include?(repo_type)

          response = RestClient.post "#{@endpoint}/projects/#{project_id}/repositories",
                                     {repository: {id: repo_id, type: repo_type}}.to_json,
                                     authorization: auth_header(),
                                     content_type: :json,
                                     accept: :json
          print_repo(JSON.parse(response))
        end

- On lines 7-11 we make the call to the API. We specify the id and type of the repository in the payload, and indicate that both the POST data and the response should be JSON, by setting the `Content-Type` and `Accept` headers. We also include the same `Authorization` header as before.
- On line 12 we parse the response, assuming it's a JSON representation of the newly created repository. We print it out using the same method as we used in the listing.

## Implement The Delete Command

Finally, let's implement the method for deleting a repository. This will be a DELETE request to the repository's own API resource: `DELETE /projects/:project_id/repositories/:repository_id`.

Update the `delete_repo` method so that it looks like this:

        def delete_repo(project_id, repo_id)
          raise "No project given"         if project_id.nil?
          raise "No repository gien"       if repo_id.nil?

          RestClient.delete "#{@endpoint}/projects/#{project_id}/repositories/#{repo_id}",
                            authorization: auth_header()
          puts "Deleted"
        end

- On lines 5-6 we make the call to the API. This time there is no content in the request, and we're not really interested in the response body either, so the only header we include is `Authorization`.
- On line 7 we print out a simple message letting the user know what's happening.

## Test Drive

We're done with our tool implementation! Let's take it for a test drive.

The tool assumes there's an existing TeamHub Project within which the operations are executed. You may want to create a separate sandbox project just for testing the tool (it's free), or you can use an existing project. In either case, the script will need a project id. Here's how you can obtain it:

- For new projects, the value you need is the same as the one you'll put in the Identifier field of the New Project view.
- For already existing projects, you can see the project identifier, among other places, in the browser address when you have navigated to the project: *https://helixteamhub.cloud/COMPANY_ID/projects/PROJECT_ID/activity.

When you have a project set up, and know it's identifier, you can start playing with the script to list, create, and delete repositories:

    ./repo list my-test-project

    ./repo create my-test-project a_git_repo git
    a_git_repo
    ====================
    Type:         git
    SSH access:   hth@helixteamhub.cloud:acme/projects/my-test-project/repositories/git/a_git_repo
    HTTPS access: https://teroparv@helixteamhub.cloud/acme/projects/my-test-project/repositories/git/a_git_repo

    ./repo create my-test-project a_hg_repo mercurial
    a_hg_repo
    ====================
    Type:         mercurial
    SSH access:   ssh://hth@helixteamhub.cloud/acme/projects/my-test-project/repositories/mercurial/a_hg_repo
    HTTPS access:

    ./repo list my-test-project
    a_hg_repo
    ====================
    Type:         mercurial
    SSH access:   ssh://hth@helixteamhub.cloud/acme/projects/my-test-project/repositories/mercurial/a_hg_repo
    HTTPS access:

    a_git_repo
    ====================
    Type:         git
    SSH access:   hth@helixteamhub.cloud:acme/projects/my-test-project/repositories/git/a_git_repo
    HTTPS access: https://teroparv@helixteamhub.cloud/acme/projects/my-test-project/repositories/git/a_git_repo

    ./repo delete my-test-project a_git_repo
    Deleted

    ./repo list my-test-project
    a_hg_repo
    ====================
    Type:         mercurial
    SSH access:   ssh://hth@helixteamhub.cloud/acme/projects/my-test-project/repositories/mercurial/a_hg_repo
    HTTPS access:

## Conclusion

In this tutorial you've learned to work with the TeamHub API, and particularly the version control repository management.

All data in TeamHub has similar APIs available, and you should be able to apply what you have learned to everything else. To get an idea of what you can do, see the API Documentation.

Your search for returned results

Your search for returned results