Using the Projects REST API
The Projects REST API provides the ability to manage decision service projects, flow projects, flow scheme projects and Policy Modeling projects.
Note that some REST operations, and some properties of the resources, don't apply for one or the other project format. That is:
-
For Policy Modeling projects, PATCH operations are only supported for updating the description property for a project version. A Policy Modeling project can't be renamed, or workspace changed through the service. POST operations are only supported for reverting a project to an earlier version.
-
For Project resources, transaction and icon properties don't exist for Policy Modeling projects.
-
For ProjectVersion resources, definition doesn't exist for Policy Modeling projects and snapshot doesn't exist for decision service projects.
Note also that authoring flows and flow schemes are a controlled release feature and therefore using the Projects REST API for these types of projects is still under development, so there may be breaking changes.
In addition to the examples provided on this page, see also the Example POST Single Deployment for a Decision Service Project Version on the Using the Deployments REST API page.
Example GET projects
The GET request URL looks like:
opa-hub/api/12.2.32/projects
The response to a get projects request looks like the following:
{
"name": "Example_Project_1",
"kind": "decision",
"workspace": "Default Collection",
"versions": {
"links": [...]
},
"links": [...]
},
{
"name": "Example_Project_2",
"kind": "decision",
"workspace": "My Collection",
"versions": {
"links": [...]
},
"links": [...]
},
{
"name": "Example_Project_3",
"kind": "policy-model",
"workspace": "Example Collection",
"versions": {
"links": [...]
},
"links": [...]
},
{
"name": "Example_Project_4",
"kind": "policy-model",
"workspace": "My Collection",
"versions": {
"links": [...]
},
"links": [...]
}Tip: You can pass a query parameter to return projects of a particular type. For example, q={"kind":"policy-model"} will return only Policy Modeling projects.
Example GET a project
The GET request URL looks like:
opa-hub/api/12.2.32/projects/Example_Project
The response to a get a decision service project request looks like the following:
{
"name": "Example_Project",
"kind": "decision",
"workspace": "Default Collection",
"versions": {
"links": [...]
},
"links": [...]
}Example GET a project version
The GET request URL looks like:
opa-hub/api/12.2.32/projects/Example_Project/versions/1
or
opa-hub/api/12.2.32/projects/Example_Project/versions/draftOrLatest
For example, the response to a get a decision service project version request looks like the following:
{
"version": 1,
"description": "New version 1 for Example Project",
"descriptionUpdatedAt": "2023-06-27T03:12:47Z",
"definition": {
"inputContract": {
"properties": [{
"uid": "bke9bsvtpkk",
"value": "the input number",
"name": "number",
"type": "number"
}
]
},
"outputContract": {
"properties": [{
"uid": "ki8x44jw4jf",
"value": "the number is big",
"name": "is_big",
"type": "boolean"
}
]
},
"rules": {
"rules": [{
"text": "Here are the rules",
"style": "normal"
}, {
"type": "rule-block",
"lines": [{
"text": "the number is big if",
"level": 0
}, {
"text": "the input number > 100",
"level": 1
}
]
}, {
"text": "",
"style": "normal"
}
]
}
}
"isDraft": false,
"createTimestamp": "2020-11-12T06:34:38Z",
"definitionHash": "f3e8d441d241167b4ac6475cd9a5059d910b15d4b40f171d433f0689de8e64df",
"links": [...]
}Another example is the response to a get a Policy Modeling project version request (opa-hub/api/12.2.32/projects/Example_OPM_Project/versions/5) which would look like the following:
{
"version": 5,
"description": "My updated version 1 comments!",
"descriptionUpdatedAt": "2023-06-27T01:07:01Z",
"inclusions-report": {
"links": [ ... ]
},
"snapshot": "... base64 data ...",
"isDraft": false,
"createTimestamp": "2022-07-28T23:43:28Z",
"definitionHash": "794c5c72933a5297f6641330d8dcc0bc90466ff44810e735f373c0c49369dfa5",
"links": [...]
}The JSON data returned by the GET response contains a "snapshot" property. The value of the snapshot property is a base-64 encoded zip file containing the Policy Modeling project for that version.
Example POST a new version of a project
The POST request URL looks like:
opa-hub/api/12.2.32/projects/Example_Project/versions
A request to post a new project version looks like the following:
{
"isDraft": false,
"description": "New version for Example Project",
"definition": <project version content>
}For example, a request to post a new decision service project version looks like the following:
{
"isDraft": false,
"description": "New version for Example Project",
"definition": {
"inputContract": {
"properties": [{
"uid": "bke9bsvtpkk",
"value": "the input number",
"name": "number",
"type": "number"
}
]
},
"outputContract": {
"properties": [{
"uid": "ki8x44jw4jf",
"value": "the number is big",
"name": "is_big",
"type": "boolean"
}
]
},
"rules": {
"rules": [{
"text": "Here are the rules",
"style": "normal"
}, {
"type": "rule-block",
"lines": [{
"text": "the number is big if",
"level": 0
}, {
"text": "the input number > 100",
"level": 1
}
]
}, {
"text": "",
"style": "normal"
}
]
}
}
}Example POST a new project (with its first version)
The POST request URL looks like:
opa-hub/api/12.2.32/projects
A request to a post a new project looks like the following:
{
"name": "Example_Project_2",
"kind": "decision" or "flow" or "flow scheme",
"workspace": "Default Collection",
"versions": {
"items":[{
"isDraft": false,
"description": "New version for Example Project 2",
"definition": <project version content>
}]
}
}More specific examples showing requests to post decision service, flow scheme and flow projects are given in the sections below.
Example POST a new decision service project (with its first version)
The POST request URL looks like:
opa-hub/api/12.2.32/projects
For example, a request to post a new decision service project looks like the following:
{
"name": "Example_Project_2",
"kind": "decision",
"workspace": "Default Collection",
"versions": {
"items":[{
"isDraft": false,
"description": "New version for Example Project 2",
"definition": {
"inputContract": {
"properties": [{
"uid": "bke9bsvtpkk",
"value": "the input number",
"name": "number",
"type": "number"
}
]
},
"outputContract": {
"properties": [{
"uid": "ki8x44jw4jf",
"value": "the number is big",
"name": "is_big",
"type": "boolean"
}
]
},
"rules": {
"rules": [{
"text": "Here are the rules",
"style": "normal"
}, {
"type": "rule-block",
"lines": [{
"text": "the number is big if",
"level": 0
}, {
"text": "the input number > 100",
"level": 1
}
]
}, {
"text": "",
"style": "normal"
}
]
}
}
}]
}
}Example POST a new flow scheme project (with its first version)
The POST request URL looks like:
opa-hub/api/12.2.32/projects
For example, a request to post a new flow scheme project looks like the following:
{
"name": "RestAPIExampleFlowScheme",
"kind": "flowScheme",
"workspace": "Default Collection",
"versions": {
"items": [
{
"definition": {
"kind": "flowScheme",
"version": 3,
"runtime": "custom",
"formatters": [
{
"kind": "number",
"name": "Currency",
"format": {
"zeroPadFractional": true,
"negativeStyle": "leadingMinus",
"groupingSymbols": [
","
],
"groupingStyle": "thirds",
"decimalSymbol": ".",
"maxDecimalPlaces": 2,
"minDecimalPlaces": 2,
"zeroPadMinDecimalPlaces": true,
"currencySymbol": "$",
"precision": 13,
"currencySymbolLocation": "beforeNumber"
}
},
{
"kind": "date",
"name": "Locale date",
"format": [
{
"kind": "month2Digit"
},
"/",
{
"kind": "day2Digit"
},
"/",
{
"kind": "year4Digit"
}
]
},
{
"kind": "number",
"name": "Number",
"format": {
"zeroPadFractional": true,
"zeroPadMinDecimalPlaces": true,
"negativeStyle": "leadingMinus",
"groupingSymbols": [
","
],
"groupingStyle": "thirds",
"decimalSymbol": ".",
"precision": 13,
"maxDecimalPlaces": 4
}
},
{
"name": "Year-month-day digits",
"kind": "date",
"format": [
{
"kind": "year4Digit"
},
"-",
{
"kind": "month2Digit"
},
"-",
{
"kind": "day2Digit"
}
]
}
],
"defaultFormatters": {
"numberInput": [
"Number"
],
"numberOutput": "Number",
"dateInput": [
"Locale date",
"Year-month-day digits"
],
"dateOutput": "Locale date"
},
"palette": [
{
"controls": [
{
"id": "label",
"kind": "label",
"text": "Label"
},
{
"id": "page",
"kind": "page",
"text": "Page"
}
],
"text": "Simple flow"
},
{
"controls": [
{
"kind": "input",
"dataType": "number",
"id": "number-currency",
"inputStyle": "textBox",
"text": "Currency",
"outputFormat": "Currency",
"inputFormats": []
},
{
"kind": "input",
"dataType": "date",
"id": "date-general",
"inputStyle": "textBox",
"text": "Date",
"outputFormat": "Locale date",
"inputFormats": [
"Year-month-day digits"
]
},
{
"id": "number-general",
"text": "Number",
"kind": "input",
"inputStyle": "textBox",
"dataType": "number",
"outputFormat": "Number",
"inputFormats": []
},
{
"id": "text",
"text": "Text",
"kind": "input",
"inputStyle": "textBox",
"dataType": "text",
"outputFormat": "",
"inputFormats": []
}
],
"text": "Filled inputs"
},
{
"controls": [
{
"id": "boolean-checkbox",
"text": "Checkbox",
"kind": "input",
"inputStyle": "checkBox",
"dataType": "boolean",
"outputFormat": "",
"inputFormats": []
},
{
"id": "boolean-radio",
"text": "Radio yes/no",
"kind": "input",
"inputStyle": "radioButtons",
"dataType": "boolean",
"outputFormat": "",
"inputFormats": []
}
],
"text": "Yes/no"
},
{
"controls": [
{
"id": "reference-dropdown",
"text": "Dropdown list",
"kind": "input",
"inputStyle": "dropDown",
"dataType": "record",
"outputFormat": "",
"inputFormats": []
},
{
"id": "reference-radio",
"text": "Radio group",
"kind": "input",
"inputStyle": "radioButtons",
"dataType": "record",
"outputFormat": "",
"inputFormats": []
}
],
"text": "Select"
},
{
"text": "More inputs",
"controls": [
{
"id": "recordlist-checkbox-multiselect",
"text": "Checkbox multi-select",
"kind": "referenceList",
"dataType": "list"
},
{
"id": "recordlist-record-collect",
"kind": "recordCollect",
"text": "Record collect"
},
{
"id": "text-area",
"text": "Text area",
"kind": "input",
"inputStyle": "textArea",
"dataType": "text",
"outputFormat": "",
"inputFormats": []
}
]
},
{
"text": "Other",
"controls": [
{
"id": "comment",
"kind": "comment",
"text": "Comment"
},
{
"id": "control-group",
"kind": "group",
"text": "Control group"
},
{
"id": "page-group",
"kind": "flowItemGroup",
"text": "Page group"
},
{
"id": "validation",
"kind": "validation",
"text": "Validation"
}
]
}
],
"localisationStrings": {
"dayFull": [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
],
"dayShort": [
"Sun",
"Mon",
"Tue",
"Wed",
"Thur",
"Fri",
"Sat"
],
"monthFull": [
"January",
"February",
"March",
"April",
"May",
"June",
"July",
"August",
"September",
"October",
"November",
"December"
],
"monthShort": [
"Jan",
"Feb",
"Mar",
"Apr",
"May",
"Jun",
"Jul",
"Aug",
"Sep",
"Oct",
"Nov",
"Dec"
],
"trueValue": "Yes",
"falseValue": "No",
"nullValue": "Null",
"numberFormatError": "Please enter a valid number.",
"dateFormatError": "Please enter a valid date.",
"dateNotExistError": "The entered date does not exist, or is before the year 0001 or after the year 9999.",
"mandatoryError": "This value is mandatory.",
"invalidReturnedDataError": "Returned data is invalid.",
"invalidValue": "Invalid value.",
"locale": "en-US"
},
"icon": "dialog",
"inputSchema": {
"type": "object",
"properties": {
"currentDate": {
"type": "string",
"format": "date",
"displayName": "Current Date",
"text": "the current date"
}
}
},
"ruleLanguage": {
"language": "en",
"formats": {
"decimalSeparator": ".",
"thousandsSeparator": ",",
"argumentSeparator": ",",
"dateFormat": "yyyy-mm-dd"
}
}
},
"isDraft": false,
"lastDefinitionHash": "string"
}
]
}
}Example POST a new flow project (with its first version)
The POST request URL looks like:
opa-hub/api/12.2.32/projects
For example, a request to post a new flow project looks like the following:
{
"name": "RestAPIExampleFlow",
"kind": "flow",
"workspace": "Default Collection",
"versions": {
"items": [
{
"definition": {
"version": 1,
"flow": {
"kind": "section",
"text": "Main section",
"uid": "15iwsecb7nz",
"schemeId": "",
"goals": [],
"schemeDataMapping": {
"uid": "yq2agnaf9lf",
"$currentDate": "the current date"
},
"rows": [
{
"kind": "page",
"schemeId": "page",
"visible": true,
"readOnly": false,
"text": "Simple Flow",
"uid": "ie91bt5ak3",
"rows": [
{
"kind": "row",
"uid": "w863sktqkk",
"controls": [
{
"kind": "label",
"uid": "u84fpxzxlan",
"schemeId": "label",
"text": "This is a simple example flow",
"visible": true,
"width": 12
}
]
},
{
"kind": "row",
"uid": "ljy6x3cmh7t",
"controls": [
{
"uid": "ummnoh0teuf",
"schemeId": "number-currency",
"kind": "input",
"dataType": "number",
"visible": true,
"readOnly": false,
"required": true,
"inputStyle": "textBox",
"question": "Currency",
"fieldName": "the employee salary",
"value": "",
"width": 12
}
]
}
]
}
]
},
"rules": {
"rules": [
{
"text": "Rules",
"style": "heading1"
},
{
"text": "This is an Intelligent Advisor rule document. The following rule-block has been created for you to replace with your own rules.",
"style": "normal"
},
{
"type": "rule-block",
"lines": [
{
"text": "the result is correct if",
"level": 0
},
{
"text": "true",
"level": 1
}
]
},
{
"text": "",
"style": "normal"
}
]
},
"scheme": "RestAPIExampleFlowScheme"
},
"isDraft": false,
"lastDefinitionHash": "string"
}
]
}
}Example GET a Policy Modeling project inclusion report
The GET request URL looks like:
opa-hub/api/12.2.32/projects/Master_OPM_Project/inclusions-report
The results are a list of all versions of the project that contain any inclusions. This report gives an idea of how inclusions have changed over time.
The response to a get a project inclusion report request looks like the following:
{
"inclusions": [{
"projectName": "Master_OPM_Project",
"projectVersion": 6,
"inclusionName": "New OPM v1",
"inclusionVersion": 3,
"inclusionLatestVersion": 3,
"upToDateFlag": true
}, {
"projectName": "Master_OPM_Project",
"projectVersion": 6,
"inclusionName": "Second Inclusion",
"inclusionVersion": 3,
"inclusionLatestVersion": 4,
"upToDateFlag": false
}, {
"projectName": "Master_OPM_Project",
"projectVersion": 5,
"inclusionName": "New OPM v1",
"inclusionVersion": 2,
"inclusionLatestVersion": 3,
"upToDateFlag": false
}, {
"projectName": "Master_OPM_Project",
"projectVersion": 5,
"inclusionName": "Second Inclusion",
"inclusionVersion": 3,
"inclusionLatestVersion": 4,
"upToDateFlag": false
},
// ...
],
"links": [
// ...
]
}For every project version in the repository with the given name, each version is assessed for its inclusions.
The list is sorted from latest version to earliest version of the project.
Only the immediate inclusions of the project are listed.
The data may also be encoded as CSV data, suitable for Excel. The client may request CSV data in one of two ways:
-
Provide an HTTP Accept header that specifies that CSV data is preferred. The format is:
Accept: text/csv -
Provide a query parameter in the URL that specifies that CSV data is required. The format is:
GET /opa-hub/api/12.2.32/projects/{project-name}/inclusions-report/?mediaType=text/csv
Example GET a Policy Modeling project version inclusion report
The GET request URL looks like:
opa-hub/api/12.2.32/projects/Master_OPM_Project/versions/4/inclusions-report
The results are a list of the specific version of the project that contain any inclusions. This report gives a quick view of the inclusions directly included in the project version.
The response to a get a project version inclusion report request looks like the following:
{
"inclusions": [{
"projectName": "Master_OPM_Project",
"projectVersion": 5,
"inclusionName": "New OPM v1",
"inclusionVersion": 2,
"inclusionLatestVersion": 3,
"upToDateFlag": false
}, {
"projectName": "Master_OPM_Project",
"projectVersion": 5,
"inclusionName": "Second Inclusion",
"inclusionVersion": 3,
"inclusionLatestVersion": 4,
"upToDateFlag": false
}
],
"links": [
// ...
]
}For the specified project name and version in the repository, the version is assessed for its inclusions.
The alias "latest" can be used to retrieve the latest version.
Only the immediate inclusions of the project are listed.
The data may also be encoded as CSV data, suitable for Excel. The client may request CSV data in one of two ways:
-
Provide an HTTP Accept header that specifies that CSV data is preferred. The format is:
Accept: text/csv -
Provide a query parameter in the URL that specifies that CSV data is required. The format is:
GET /opa-hub/api/12.2.32/projects/{project-name}/versions/{version-number}/inclusions-report/?mediaType=text/csv
Example POST a new version of a Policy Modeling project by reverting to an earlier version
The POST request URL looks like:
opa-hub/api/12.2.34/projects/EnergySaver/versions/4/revert
The request body will have the following format:
{
"description": "Revert to version 4",
}The response to a POST request contains details of the new project version created as a result of the revert operation:
{
"version": 6,
"description": "Revert to version 4",
"createTimestamp": "2024-02-25T21:39:24Z",
}
Example PATCH a project version
The PATCH request URL looks like:
opa-hub/api/12.2.32/projects/New+Project/versions/2
The structure expected for a PATCH request for the Policy Modeling version resource is as follows:
{
"description": "New version 2 for New Project",
}The response to a PATCH request contains the updated description, along with the date and time at which it was updated:
{
"version": 2,
"description": "New version 2 for New Project",
"descriptionUpdatedAt": "2023-06-27T03:12:47Z",
"definition": {
"version": 5,
"inputContract": {},
"outputContract": {},
"rules": {
...
},
"ruleLanguage": {
"language": "en",
"formats": {
"decimalSeparator": ".",
"thousandsSeparator": ",",
"argumentSeparator": ",",
"dateFormat": "yyyy-mm-dd"
}
},
"documents": []
},
"inclusions-report": {
"links": [
...
]
},
"isDraft": false,
"createTimestamp": "2023-06-21T23:57:27Z",
"definitionHash": "9e47aff39bd3fbda80b99af456015a952da081f771487f110dd3710cbf859691",
"links": [
...
]
}