1. REST API for Managing Issues in Oracle Developer Cloud ServiceREST API for Managing Issues in Oracle Developer Cloud Service
  2. Quick Start

Quick Start

Set up your environment and create your first issue for Oracle Developer Cloud Service using the REST API by performing the following tasks.

Step 1: Obtain Account Information

From your account administrator, obtain the appropriate account credentials to enable you to use Oracle Developer Cloud Service. Specifically, you will need:

  • Username and password

  • The URL of your Oracle Developer Cloud Service instance, which is listed in the welcome email you receive with your trial or purchased subscription.

Step 2: Install cURL

You can use the cURL command-line tool to access the REST API for Managing Issues in Oracle Developer Cloud Service.

To install cURL:

  1. In your browser, navigate to the cURL Home Page.

  2. Locate the SSL-enabled version of the cURL software that corresponds to your operating system, download the ZIP file, and install the software.

Step 3: Create an Oracle Developer Cloud Service Project

Create an Oracle Developer Cloud Service project for which you will create issues using the REST API. To create this project, follow the instructions in Creating a Project in Using Oracle Developer Cloud Service. If you create a project with an initial repository, you can visit the Project page and fetch the <host-url>, <org-id>, and <project-id> needed to construct the URL used in the cURL commands for accessing the REST API used to create issues. This information is displayed in the SSH or Maven URLs on the right side of the Project page in Oracle Developer Cloud Service.

Step 4: Retrieve the “Form” You Use To Create 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 not convenient. Alternatively, you could create a file that contains the JSON data for the issue and then use the -d@<filename> option to call in the file. However, typing the entire JSON representation from scratch in a text editor is not 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. You can use a modified version of the saved file in the cURL command for creating new issues.

To retrieve the "form" and save it to a file named "issue-template":

curl -i 
-X GET -s 
http://developer.us.oraclecloud.com/dev-org/rest/dev-org_pubapi_203132/issues/v2/issues/create-form 
>issue-template

The JSON representation is returned, in a single line. The following has been 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 is 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 'Content-type:application/json' -d@issue-new 
http://developer.us.oraclecloud.com/qa-dev/rest/qa-dev_pubapi_203132/tasks/issues/v2/issues

If the request is successful, the server returns 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. Such an extraction is a simple matter for a program, but is not convenient to perform interactively, on the command line.