Build API

Introduction

The Build API allows you to manage deployment packages and create new deployment packages using our build server. You will need the information from the Teamserver API as input for these API calls.

You can use webhooks to trigger CI/CD pipelines which use this API. These are described in Webhooks.

The image below provides a domain model representation of the concepts discussed below and how these are related:

Authentication

The Build API requires authentication via API keys that are bound to your Mendix account.

Obtaining an API Key

To obtain a Mendix API key, follow the instructions in the API Keys section of Mendix Profile.

Using Authentication Headers

Use the following request headers to authenticate an API call:

• Mendix-Username – the login name of the requesting user with the required privileges in the Mendix Platform
• Mendix-ApiKey – the API key of this user

Configuring Permissions

To perform an action via the Build API, you need API Rights permissions. This can be configured from the Permissions tab of your app’s Environments page.

API Calls

Retrieve Packages

Description

Retrieves all deployment packages that are available for a specific app that the authenticated user has access to as a regular user. These packages can be found if you click Details on an app in the Nodes screen in the Mendix Platform.

HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/packages

Request

Parameter

• AppId (String) : Subdomain name of an app.

Example

GET /api/1/apps/calc/packages HTTP/1.1
Host: deploy.mendix.com
Accept: */*
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

Output

List of objects with the following key-value pairs:

• PackageId (String) : Unique identification of the package.
• Name (String) : Name of the package.
• Description (String) : Description of the package.
• Version (String) : Package version. This is also the name of the tag on the project team server.
• Creator (String) : Uploader or creator of this package.
• CreationDate (Date) : Date that the package became available in the portal. This can be the upload date or the date that a build was created in the portal.
• Status (String) : Status of the package. A package is ready to use if the status is ‘Succeeded’. Possible values: Succeeded, Queued, Building, Uploading and Failed.
• Size (Long) : Size of the package in bytes.

Error Codes

Example

[{
     "Name" :  "Main line-1.1.5.9.mda" ,
     "Status" :  "Succeeded" ,
     "Description" :  "Initial app" ,
     "Creator" :  "Richard Ford" ,
     "CreationDate" :  1404739654045 ,
     "Version" :  "1.1.5.9" ,
     "PackageId" :  "4ee10492-6cfc-4582-b825-a9040c0988ad" ,
     "Size" :  1999059
},{
     "Name" :  "Main line-2.5.4.63.mda" ,
     "Status" :  "Succeeded" ,
     "Description" :  "Add scientific mode" ,
     "Creator" :  "Richard Ford" ,
     "CreationDate" :  1404990271835 ,
     "Version" :  "2.5.4.63" ,
     "PackageId" :  "b3d14e53-2654-4534-b374-9179a69ef3cf" ,
     "Size" :  7731521
}]

Retrieve Package

Description

Retrieves a specific deployment package that is available for a specific app that the authenticated user has access to as a regular user. This package can be found if you click Details on an app in the Nodes screen in the Mendix Platform.

HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/packages/<PackageId>?url=<Boolean>

Request

Parameters

• AppId (String) : Subdomain name of an app.
• PackageId (String) : Id of the deployment package.
• url (Boolean) (default: false): Indicates whether the API should return a URL pointing to the location of the package.

Example

GET /api/1/apps/calc/packages/b3d14e53-2654-4534-b374-9179a69ef3cf?url=true HTTP/1.1
Host: deploy.mendix.com
Accept: */*
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

Output

An object with the following key-value pairs:

• PackageId (String) : Unique identification of the package
• Name (String) : Name of the package
• Description (String) : Description of the package
• Version (String) : Package version. This is also the name of the tag on the project team server
• Creator (String) : Uploader or creator of this package
• CreationDate (Date) : Date that the package became available in the portal. This can be the upload date or the date that a build was created in the portal
• Status (String) : Status of the package. A package is ready to use if the status is ‘Succeeded’. Possible values:
  • Succeeded
  • Queued
  • Building
  • Uploading
  • Failed
• Size (Long) : Size of the package in bytes
• Url (object): A JSON object containing the following:
  • Location (String): The URL pointing to the package file.
  • TTL (Long): How long the URL is valid (in seconds).

Error Codes

Example

{
    "Name" :  "Main line-2.5.4.63.mda" ,
    "Status" :  "Succeeded" ,
    "Description" :  "Add scientific mode" ,
    "Creator" :  "Richard Ford" ,
    "CreationDate" :  1404990271835 ,
    "Version" :  "2.5.4.63" ,
    "PackageId" :  "b3d14e53-2654-4534-b374-9179a69ef3cf" ,
    "Size" :  15342295S,
    "Url": {
        "Location": "https://url/to/download/the/package/file",
        "TTL": 900
    }
}

Delete Package

Description

Deletes a specific deployment package that is available for a specific app that the authenticated user has access to as a regular user. This package can be found if you click Details on an app in the Nodes screen in the Mendix Platform.

HTTP Method: DELETE
URL: https://deploy.mendix.com/api/1/apps/<AppId>/packages/<PackageId>

Request

Parameters

• AppId (String) : Subdomain name of an app
• PackageId (String) : Id of the deployment package

DELETE /api/1/apps/calc/packages/b3d14e53-2654-4534-b374-9179a69ef3cf HTTP/1.1
Host: deploy.mendix.com

Accept: */*
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

Error Codes

⚠ Download Package

Downloads a specific deployment package that is available for a specific app that the authenticated user has access to as a regular user. This package can be found if you click Details on an app in the Nodes screen in the Mendix Platform.

HTTP Method: GET
URL: https://deploy.mendix.com/api/1/apps/<AppId>/packages/<PackageId>/download

Request

Parameters

• AppId (String) : Subdomain name of an app.
• PackageId (String) : Id of the deployment package.

GET /api/1/apps/calc/packages/b3d14e53-2654-4534-b374-9179a69ef3cf/download HTTP/1.1
Host: deploy.mendix.com
Accept: */*
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

Output

Error codes

Start Building Deployment Package

Start the process to build a deployment package, based on the team server project of a specific app that the authenticated user has access to as a regular user. This package can be found if you click Details on an app in the Nodes screen in the Mendix Platform. For a Free App, this will also trigger a deployment of the new package.

HTTP Method: POST
URL: https://deploy.mendix.com/api/1/apps/<AppId>/packages

Request

Parameter

• AppId (String) : Subdomain name of an app.

Payload

The payload depends on whether the app is held in a Git repository or an SVN repository.

An object with the following key-value pairs:

• Branch (String) : Name of the branch.
  • For SVN, this is ’trunk’ for the main line or ‘branches/branch name’ for a specific branch.
  • For Git, this is ‘main’ for the main line or ‘branches/branch name’ for a specific branch.
• Revision (String) : Number of the revision to build a package from.
  • For SVN, this is an integer reflecting the revision number.
  • For Git, this is the commit hash. The API will accept either the short commit hash or the full commit hash.
• Version (String) : Package version. This will also be the name of the tag on the project team server.
• Description (String) : Description of the package.

Example

POST /api/1/apps/calc/packages HTTP/1.1
Host: deploy.mendix.com
Accept: */*
Mendix-Username: richard.ford51@example.com
Mendix-ApiKey:  26587896-1cef-4483-accf-ad304e2673d6

{
     "Branch" : "branches/feature" ,
     "Revision" :  "63" ,
     "Version" :  "2.5.4" ,
     "Description" :  "Add scientific mode"
}

Output

An object with the following key-value pair:

• PackageId (String) : Unique identification of the package. This string can be used to get the build status of the package later.

Error codes

Example

{
     "PackageId" :  "b3d14e53-2654-4534-b374-9179a69ef3cf"
}

If calc is the example app, you can find the status of the build by using GET /api/1/apps/calc/packages/b3d14e53-2654-4534-b374-9179a69ef3cf HTTP/1.1 and looking for a return status of Succeeded.