REST API for Oracle Visual Builder Studio

Quick Start

Complete these tasks to set up your environment and use the REST API for Oracle Visual Builder Studio to create and manage builds, pipelines, and issues by performing these tasks.

Prerequisites

Prerequisite	More Information
Install cURL	Use cURL
Set up authentication	Authenticate

Step 1: Get Your Account Information

Get the account credentials to you need to use VB Studio from your account administrator. Specifically, you'll need:

Username and password
Your VB Studio instance's URL, which is listed in the welcome email you receive with your trial or purchased subscription.

Step 2: Install cURL

You use the cURL command-line tool for accessing the REST API for Oracle Visual Builder Studio.

To install cURL:

In your browser, navigate to the cURL Home Page.
Locate and download the SSL-enabled cURL software for your operating system, then install it.

Step 3: Create a VB Studio Project

Create a VB Studio project for which you'll create issues using the REST API. To create this project, follow the instructions in Create a Project in Using Visual Builder Studio.

If you create a project with an initial repository, you can visit the Project Home page and fetch the server, org-id, and org-id_project-id needed to construct the URL used in the curl commands for accessing the REST API used to create issues.

From your project's Project Home page, click on the Repositories tab, and look at the Maven or Git repository URL. Look for the part before /maven/ or /scm/repository-name.git at the end of each respective URL. Some projects may also include a numeric value appended to the project name.

Note:

Since you're the project owner, you can select Project Administration in the navigator, click the Properties tile, then look in the Identifier field to find the org-id_project-id part of the URL.

From here, you can decide whether you want to get started with Issues or Builds:

Continue to Step 4 to get started with Issues.
Go to Start a Build for a Job or Start a Pipeline to get started with Builds.

Step 4: Retrieve the "Form" for Creating an Issue

To create a new issue, you need to send the entire JSON representation for the issue, quite a large chunk of data, to the server. With curl, you could use the -d option followed by the all of the JSON data for the issue on the command line. This is quite inconvenient. You'd be better off creating a file that contains the JSON data for the issue and then using the -d@<filename> option to call in the file. However, typing the entire JSON representation from scratch in a text editor isn't convenient either, so the recommended course of action is to first fetch the "form", the JSON representation for an issue, using a GET HTTP command with the issues/create-form resource and saving it to a file. Later, you can use a modified version of the saved file in the curl command for creating new issues.

Here's how to retrieve the "form" and save it to a file named issue-template:


curl -i 
-X GET -s -H "Accept: application/vnd.oracle.resource+json" 
https://myinstance.oracle.com/myorg/rest/myorg_pubapi_203132/issues/v2/issues/create-form 
>issue-template

The JSON representation is returned, in a single line. Here it is after being formatted for readability:


{"createIssue":{
  "links":[
    {"rel":"self",
    "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/create-form"},
    {"rel":"create",
    "href":"http://developer.us.oraclecloud.com/dev-org/dev-org_pubapi_203132/issues/v2/issues"}
  ],
    "summary":"New Task",
    "type":"Defect",
    "severity":{
      "id":4,
      "value":"normal",
      "sortkey":400},
      "status":{
        "id":1,
        "value":"UNCONFIRMED",
        "isActive":true,
        "isOpen":true,
        "sortkey":100},
        "priority":{
          "id":3,
          "value":"Normal",
          "sortkey":300},
        "release":{
          "id":1,
          "value":"---",
          "sortkey":0,
          "product":{
            "id":1}
          },
        "product":{
          "id":1,
          "name":"Default",
          "description":"default product",
          "isActive":true,
          "defaultRelease":{
            "id":1,
            "value":"---",
            "sortkey":0,
            "product":{
              "id":1}
            },
            "defaultComponent":{
              "id":1,"product":{
                "id":1},
              "name":"Default",
              "description":"default component"},
            "releases":[
              {"id":1,
              "value":"---",
              "sortkey":0,
              "product":{
                "id":1}
              },
              {"id":2,
              "value":"0.0.1",
              "sortkey":10,
              "product":{
                "id":1}
              }
            ],
          "components":[
        {"id":1,
        "product":{
        "id":1},
      "name":"Default",
      "description":"default component"}
    ],
  "releaseTags":[]}
}}

Every resource returned by the server contains a root object specifying the resource that was used in the request, in this case createIssue. However, when the JSON of a resource is sent to the server for create or update operations, this root object must be stripped off, or the server will reject the request. This is a tedious task if it's done manually, but is quite a simple task for a program to do.

In an editor, remove the heading {"createIssue":' and the last trailing curly brace (}). Then save the file.

Step 5: Edit the JSON Representation of the Issue to Create

Open the template issue file in the text editor, change the summary field to "New Story", change the type field to "Story", and save the changes to a new file, for example issue-new.

Your saved file should now look like this, with the changes you made in bold:


{"links":[
  {"rel":"self",
   "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/create-form"},
  {"rel":"create",
   "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues"}
  ],
  "summary":"New Story",
  "type":"Story",
  "severity":{
    "id":4,
    "value":"normal",
    "sortkey":400},
    "status":{
      "id":1,
      "value":"UNCONFIRMED",
      "isActive":true,
      "isOpen":true,
      "sortkey":100},
    "priority":{
      "id":3,
      "value":"Normal",
      "sortkey":300},
    "release":{
      "id":1,
      "value":"---",
      "sortkey":0,
      "product":{
        "id":1}
      },
      "product":{
        "id":1,
        "name":"Default",
        "description":"default product",
        "isActive":true,
        "defaultRelease":{
          "id":1,
          "value":"---",
          "sortkey":0,
          "product":{
            "id":1}
          },
        "defaultComponent":{
          "id":1,
          "product":{
            "id":1},
          "name":"Default",
          "description":"default component"},
        "releases":[
          {"id":1,
           "value":"---",
           "sortkey":0,
           "product":{
             "id":1}
            },
            {"id":2,
             "value":"0.0.1",
             "sortkey":10,
             "product":{
               "id":1}
             }
           ],
         "components":[
           {"id":1,
            "product":{
              "id":1},
            "name":"Default",
            "description":"default component"}
          ],
        "releaseTags":[]}
      }

Step 6: Create the Issue

To create the new issue, use the following command:


curl -i 
-X POST 
-s -H "Accept: application/vnd.oracle.resource+json" -H "Content-type: application/vnd.oracle.resource+json"  -d@issue-new 
https://myinstance.oraclecloud.com/myorg/rest/myorg_pubapi_203132/tasks/issues/v2/issues

If the request is successful, the server will return the entire JSON representation of the newly created issue:


{"issue":{
  "links":[
    {"rel":"self",
     "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/1"},
    {"rel":"canonical",
     "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/1"},
    {"rel":"create-form",
     "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/create-form"},
    {"rel":"collection",
     "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues"},
    {"rel":"search-form",
     "href":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/search-form"}
  ],
  "id":1,
  "version":"1498782045181",
  "creationDate":1498782045175,
  "modificationDate":1498782045181,
  "summary":"New Story",
  "description":"",
  "wikiRenderedDescription":"",
  "tags":[],
  "sumOfSubIssuesEstimatedTime":0,
  "remainingTime":0,
  "sumOfSubIssuesRemainingTime":0,
  "sumOfSubIssuesStoryPoints":0,
  "url":"http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/task/1",
  "type":"Story",
  "externalLinks":[],
  "reporter":{
    "id":1,
    "loginName":"joe@example.com",
    "realname":"Joe",
    "gravatarHash":"68aa64f7d0abfd8929c261f78b60fd27"},
  "ccs":[
    {"id":1,
     "loginName":"joe@example.com",
     "realname":"Joe",
     "gravatarHash":"68aa64f7d0abfd8929c261f78b60fd27"}
   ],
  "severity":{
    "id":4,
    "value":"normal",
    "sortkey":400},
  "status":{
    "id":1,
    "value":"UNCONFIRMED",
    "isActive":true,
    "isOpen":true,
    "sortkey":100},
  "priority":{
    "id":3,
    "value":"Normal",
    "sortkey":300},
  "release":{
    "id":1,
    "value":"---",
    "sortkey":0,
    "product":{
      "id":1}
    },
  "product":{
    "id":1,
    "name":"Default",
    "description":"default product",
    "isActive":true},
  "subIssues":[],
  "timeSpent":[],
  "sumOfSubIssuesTimeSpent":0,
  "attachments":[],
  "duplicates":[],
  "customFields":{
    "iteration":"---"},
  "commits":[],
  "comments":[]
}}

Notice that the response contains the root object issue.

You created an issue by manually typing its known URL on the command line. However, a program should never store a hardcoded URL as a static string in a configuration file. The issue/create-form JSON representation contains a links list property that contains a URL whose rel (relation) is create:


"links":[
    ...
    {
      "rel":"create","href":"http://developer.us.oraclecloud.com/qa-dev/rest/qa-dev_pubapi_203132/issues/v2/issues"
    }
]

The href property of this link is the URL that would be used with a POST request to create a new issue. A program would extract this URL from the response body returned by the issues/create-form resource and use it to create an issue. Again, an extraction like this is a simple matter for a program, but isn't convenient to perform interactively, on the command line.