Server-side REST API

The server-side REST API allows you to effectively access the StarTeam Server resources.

In this topic:

Overview

The server-side REST service runs within the server process, using the server caches when executing commands. MPX is not required. All the basic operations for server components, project, views, and items are supported.

Back to top

Start the REST service

To start the REST service, you need to configure the REST API port.

To configure the port:

1. Ensure that the following entry in the starteam-server-configs.xml file stores the ServerRESTAPIPort value of 49206:

   Copy code

   <option name="ServerRESTAPIPort" value="49206"/>

Note: If ServerRESTAPIPort is not set, the service will automatically start on the next available port. The above setting will be updated with this port value.

2. Enable the https secure port by using the following setting:

   Copy code

   <option name="ServerRESTAPISecure" value="1"/>

The following entry in the server log will indicate if the REST service started successfully:

Sample scripts using cURL (https://curl.se/) are installed in the Samples folder, under the StarTeam server installation folder.

Back to top

Disable the REST service

To disable the server-side REST service, in the starteam-server-configs.xml file, set the value of ServerRESTAPIPort to -1:

<option name="ServerRESTAPIPort" value="-1"/>

Back to top

Configure certificates for a secure protocol

StarTeam Server REST uses Windows HTTP Server API and requires that the X.509 certificate is stored in Local Computer/Personal/Certificates.

The certificate must be configured for a specific port used by StarTeam Server REST. Use the Windows Netsh utility to configure the certificate.

To configure the certificate for a secure protocol:

1. If the certificate and key are in two separate files (.crt and .key), convert them to .p12 using openssl:

..\openssl pkcs12 -export -in "mycert.crt" -inkey "mycert.key" -out "mycert.p12" -name myCert -passin pass:changeit -passout pass:changeit

2. On your local computer, click Start, and type mmc.exe .
3. In the MMC window, go to File > Add/Remove Snap-in.
4. In the Add or Remove Snap-ins window, select Certificates(Local Computer)/Personal/Certificates, and click Add.
5. In the new dialog box, select All Tasks/import to import the certificate.

   Note: Ensure the Root CA for the certificate is trusted. This requires importing the certificate to Certificates/Local Computer/Trusted Root certificates/Certificates.

6. In the MMC window, open the certificate. In the Details pane, select Thumbprint, and copy the hash value.

   The thumbprint hash should not contain any spaces. For example: df5bb4713271bbfcad49e82c7ac8e8e9a75b48a7.

7. Open the Command Prompt window. Using the Netsh utility, associate the certificate with the Server REST https port by running the following command:

   netsh http add sslcert ipport=0.0.0.0:yourport certhash=*yourthumbprint* appid={00000000-0000-0000-0000-000000000000}

After you run the command, the following message appears: SSL Certificate successfully added.

If another certificate is associated with this port, an error occurs.

Possible actions:

• To view the certificate that is currently associated with the port, use the following command:

  netsh http show sslcert ipport=0.0.0.0:yourport

• To delete the certificate that is currently associated with the port, use the following command:

  netsh http delete sslcert ipport=0.0.0.0:yourport

Back to top

See also:

• Authentication
• Server components
• User management
• Project and view
• Items