Handling annotations by using API URLs

About this task

The annotation web service runs on the Liberty server. After the annotation REST API is enabled, you can run requests to handle annotations by using URLs with other tools, for example, Postman. For more information about handling annotations in IBM® AD Analyze Client, see section Handling Annotations.

Note:

In case Authentication Server (DEX) is configured and running, a token that is generated from DEX will be required to send in the header of any request that is made to the Annotations API. The token needs to be placed in the Authorization header as Bearer <dex_token>. For example, curl -H "Authorization: Bearer YWxpY2U6c2VjcmV0" http://localhost:9080/annotations/project/create/ProjectName

Procedure

Enter one of the following endpoints with the corresponding request body.
The create endpoint: libertyURL/annotations/project/create/ProjectName
When the annotation property of a project is null, this endpoint can be used to create annotations. Otherwise, use the update endpoint. Specify the annotation keys and values that you want to create in the request body. See the following example:
POST method:
http://localhost:9080/annotations/project/create/Regression
Body:
					{
      "metadata_name1": "metadata_value1",
      "metadata_name2": "metadata_value2",
      "metadata_name3": "metadata_value3",
      "metadata_name4": "metadata_value4"
    }
Response:
Create annotations operation: successful
The update endpoint: libertyURL/annotations/project/update/ProjectName
This endpoint can be used to update existing annotations. If the annotation property of a project is null, this endpoint can also be used to create annotations. Specify the annotation keys and values that you want to update in the request body. See the following example:
PUT method:
http://localhost:9080/annotations/project/update/Regression
Body:
					{
      "metadata_name1_to_update": "metadata_value_updated",
      "metadata_name2_to_update": "metadata_value_updated",
      "metadata_name3_to_update": "metadata_value_updated",
      "new_metadata_name": "metadata_value"
    }
Response:
Update annotations operation: successful
Once a create or update request is successful, the annotations will be displayed as metadata both in Mainframe Project Service and in IBM AD Analyze Client.
  • In Mainframe Project Service, a new property metadata that represents the annotations of a project will be displayed.
  • In IBM AD Analyze Client, a new Metadata column that only contains the annotations is displayed in the Explore projects view.
    The annotations displayed in the Explore projects view
    If you need to check the key name and value for the annotations, select a project that contains annotations in the Explore projects view, and go to the left bottom corner where the project properties are displayed. Then, click the Custom Details tab to check the key name and value for the annotations.
    check the key name and value for the annotations
The delete endpoint: libertyURL/annotations/project/delete/ProjectName
This endpoint can be used to delete existing annotations. Specify the annotation keys that you want to delete in the request body. The annotation values are optional. See the following example:
DELETE method:
http://localhost:9080/annotations/project/delete/Regression
Body:
					{
      "metadata_name1_to_delete": "",
      "metadata_name2_to_delete": "",
      "metadata_name3_to_delete": ""
    }
Response:
Delete annotations operation: successful
The get endpoint: libertyURL/annotations/project/get/ProjectName
This endpoint returns the annotations that are set at the project level. See the following example:
GET method:
http://localhost:9080/annotations/project/get/Regression
Response:
{
    "annotations_key_1": "annotations_value_1",
    "annotations_key_2": "annotations_value_2",
    "annotations_key_3": "annotations_value_3",
    "annotations_key_4": "annotations_value_4"
}