Back to Top

Listing DB ChangeScripts for a Release with the Native API

Some BuildMaster functionality does not have a documented API. To access this functionality through an automated process, it may be necessary to use the native API. There are three interfaces for the native API: JSON, SOAP, and SQL. The native API interfaces take the same parameters and return the same data, so you should use the most convenient one for your programming environment.


Using the JSON API

The JSON interface for the native API can be used by any program that can perform HTTP requests and decode JSON. To retrieve a list of database change scripts for an application, we need to perform two requests:

GET or POST /api/json/Applications_GetApplications?key=«api-key»

The first request gives us a JSON array containing JSON objects with properties of applications in BuildMaster. There are many properties, but right now we only care about Application_Name and Application_Id. Find the Application_Id of the application you want and feed it into the next request:

GET or POST /api/json/DatabaseChangeScripts_GetChangeScripts?key=«api-key»&Application_Id=«application-id»

The response contains a JSON array of JSON objects with properties about the application, release, deployable, and script, as well as the usernames and timestamps of the creation and last modification the script.

Using the SOAP API

The SOAP interface for the native API is useful for .NET programmers. Visual Studio can automatically generate code to connect to a SOAP API. To do this, add a Service Reference to your project with the URL http://your-buildmaster-installation/api/soap.

Adding a Service Reference

Here is an example of code that interacts with the SOAP API:

using System;
using System.Data;
using System.Linq;

namespace SoapApiExample
{
    static class Program
    {
        const string APIKey = "«api-key»";
        const string ApplicationName = "«application-name»";

        static void Main(string[] args)
        {
            using (var client = new buildmaster.ApiServiceSoapClient("ApiServiceSoap"))
            {
                var applicationId = (from app in client.Applications_GetApplications(APIKey, null, null).AsEnumerable()
                                     where string.Equals(app.Field<string>("Application_Name"), ApplicationName, StringComparison.OrdinalIgnoreCase)
                                     select app.Field<int>("Application_Id")).First();

                var releases = from script in client.DatabaseChangeScripts_GetChangeScripts(APIKey, applicationId, null, null, null).AsEnumerable()
                               let s = new
                               {
                                   Release_Number = script.Field<string>("Release_Number"),
                                   Script_Name = script.Field<string>("Script_Name")
                               }
                               group s by s.Release_Number;

                foreach (var scripts in releases)
                {
                    Console.WriteLine($"Release {scripts.Key}");
                    foreach (var s in scripts)
                    {
                        Console.WriteLine(s.Script_Name);
                    }
                    Console.WriteLine();
                }
            }
        }
    }
}

Using the SQL API

The SQL interface for the native API is useful for one-off applications because the code can run directly in the database, saving you the trouble of writing a full program.

The SQL interface also has access to some procedures not available in the JSON or SOAP interfaces. These internal procedures are not supported, but you may find them useful when writing a script. Additionally, because it operates directly on the database, the SQL interface is not restricted to procedures. In some cases, it may be easier to write one large query instead of many smaller ones.

Despite the increased power (and therefore danger) of the SQL interface, it can be used in the same way as the JSON or SOAP interfaces:

DECLARE @Application_Id INT

SELECT @Application_Id = [Application_Id] FROM [Applications] WHERE [Application_Name] = '«application-name»'

EXEC [DatabaseChangeScripts_GetChangeScripts]
  @Application_Id = @Application_Id