New REST endpoints on Business Central
--
REST API has now branch management support
Maven Options
Common maven actions for projects in Business Central can be triggered by REST API and offer a branch optional parameter on version 7.31.0.
We can make great integrations to compile, install, test and deploy automatically with any branch and project without the User Interface.
Use the old endpoints for the master branch or make a POST request to the new endpoints to specify the target branch.
Branch Management
Business Central version 7.32.0 adds REST endpoints to manage branches along with projects and spaces.
We can now get, add or remove branches and all clients gets a refreshed User Interface.
Cheat Sheet
The base URL for the endpoints below is /spaces/{name}/projects/{name}
- Compile branch: POST
/branches/{name}/maven/compile - Install branch: POST
/branches/{name}/maven/install - Test branch: POST
/branches/{name}/maven/test - Deploy branch: POST
/branches/{name}/maven/deploy - Get branches: GET
/branches - Add branch: POST
/branches - Remove branch: DELETE
/branches/{name}
To add a branch, send data in JSON format:
{
"newBranchName": "branch01",
"baseBranchName": "master"
}Examples
In Business Central, the REST API works asynchronously, which means the user does not have to wait the request to be completed. Each request is considered a Job and gets an ID assigned. Jobs can be pulled from server to check status, outputs and possible error messages.
- Download Wildfly 18.0.1.Final here
- Download Business Central version ≥ 7.32.0 here
- Deploy Business Central war file to Wildfly:
$ unzip wildfly-18.0.1.Final.zip$ cp business-central-7.31.0.Final-wildfly14.war \
wildfly-18.0.1.Final/standalone/deployments
4. Add a user with REST role:
$ ./wildfly-18.0.1.Final/bin/add-user.sh -a \
--user bc \
--password bc \
--role admin,rest-all5. Increase JVM memory:
$ sed -i -e 's/-Xms64m/-Xms128m/' \
wildfly-18.0.1.Final/bin/standalone.conf$ sed -i -e 's/-Xmx512m/-Xmx1024m/' \
wildfly-18.0.1.Final/bin/standalone.conf
6. Start Wildfly:
$ ./wildfly-18.0.1.Final/bin/standalone.sh -c standalone-full.xml7. Create a Space:
$ curl -X POST \
-u 'bc:bc' \
-H "content-type: application/json" \
-d '{"name": "Space123", "owner": "bc"}' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/"The CURL utility is used here in a but any REST client would work.
We got the response below:
{
"jobId": "1576173848604-1",
"status": "APPROVED",
"spaceName": "Space123",
"owner": "bc",
"defaultGroupId": null,
"description": null
}The status APPROVED means that the request was accepted and put on queue to be processed. We can query jobs by ID to find out its completion status and messages:
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/jobs/1576173848604-1"{
"status": "SUCCESS",
"jobId": "1576173848604-1",
"result": "Space Space123 is created successfully.",
"lastModified": 1576173848642,
"detailedResult": null
}
8. Create a project:
$ curl -X POST \
-u 'bc:bc' \
-H "content-type: application/json" \
-d '{"name": "ProjABC"}' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects"Notice that we added Space123 to REST endpoint to match the space resource we created on step 7. This applies to all endpoints in Business Central.
9. Get, add, compile and remove branches:
# Get branches
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches"[{"name":"master"}]# Add branch
$ curl -X POST \
-u 'bc:bc' \
-H "content-type: application/json" \
-d '{"newBranchName": "b1", "baseBranchName": "master"}' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches"{
"jobId": "1576175811141-3",
"status": "APPROVED",
"spaceName": "Space123",
"projectName": "ProjABC",
"newBranchName": "b1",
"baseBranchName": "master",
"userIdentifier": "bc"
}# Check Job
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/jobs/1576175811141-3"{
"status": "SUCCESS",
"jobId": "1576175811141-3",
"result": null,
"lastModified": 1576175811204,
"detailedResult": null
}# Get branches
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches"[
{"name": "b1"},
{"name": "master"}
]# Compile branch
$ curl -X POST \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches/b1/maven/compile"{
"jobId": "1576175811233-4",
"status": "APPROVED",
"spaceName": "Space123",
"projectName": "ProjABC",
"branchName": "b1",
}# Check Job
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/jobs/1576175811233-4"{
"status": "SUCCESS",
"jobId": "1576175811233-4",
"result": null,
"lastModified": 1576175811257,
"detailedResult": null
}# Remove branch
$ curl -X DELETE \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches/b1"{
"jobId": "1576175811421-5",
"status": "APPROVED",
"spaceName": "Space123",
"projectName": "ProjABC",
"branchName": "b1",
"userIdentifier": "bc"
}# Check Job
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/jobs/1576175811421-5"{
"status": "SUCCESS",
"jobId": "1576175811421-5",
"result": null,
"lastModified": 1576175811452,
"detailedResult": null
}# Get branches
$ curl -X GET \
-u 'bc:bc' \
"http://127.0.0.1:8080/business-central-7.32.0.Final-wildfly14/rest/spaces/Space123/projects/ProjABC/branches"[{"name":"master"}]
