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:
Body:http://localhost:9080/annotations/project/create/Regression
Response:{ "metadata_name1": "metadata_value1", "metadata_name2": "metadata_value2", "metadata_name3": "metadata_value3", "metadata_name4": "metadata_value4" }
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:
Body:http://localhost:9080/annotations/project/update/Regression
Response:{ "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" }
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.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.
- 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:
Body:http://localhost:9080/annotations/project/delete/Regression
Response:{ "metadata_name1_to_delete": "", "metadata_name2_to_delete": "", "metadata_name3_to_delete": "" }
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:
Response:http://localhost:9080/annotations/project/get/Regression
{ "annotations_key_1": "annotations_value_1", "annotations_key_2": "annotations_value_2", "annotations_key_3": "annotations_value_3", "annotations_key_4": "annotations_value_4" }