BuildMaster Documentation

Native API Methods

  • Last Modified: 2018-02-26

The other endpoints should be used instead of the Native API Methods when possible, as they are much easier to use and will likely not change from version-to-version.

API Usage

All of these methods require that an API Key with Native API Access is passed into each request; see Using API Keys for more information.

Method Listing

The Native API Methods are automatically documented by a special page in the software. To see the API Methods for your specific version, go to Administration > Reference > API Methods, or directly visit http://your-buildmaster-installation/reference/api in your installation.

Using 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.

JSON-based Access

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.

SOAP-based Access

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();
            }
        }
    }
}
}

SQL-based Access

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

Have a question? Try the Q&A Forum

Our documentation is now Open Source and on GitHub. We highly encourage our users to contribute and get involved! .