AE v24 REST API

[Michael A. Lowry]

Automation Engine version 24 introduces substantial updates to the AE REST API.

Most notably, v24 adds the ability to create, read, update, and delete objects. The documentation page Using the AE REST API provides examples for several things, but not these "CRUD" operations. I did some basic tests to figure out how it works.

Operation	HTTP method & AE REST API endpoint	Body
Create	​POST /{client_id}​/objects	Complete JSON object definition
Read	GET /{client_id}/objects/{object_name}	NA
Update	PATCH /{client_id}/objects/{object_name}	Partial JSON object definition. Omit type, name, and path properties.
Delete	DELETE /{client_id}/objects/{object_name}	NA

The GET method is essentially equivalent to an XML export, but delivering a JSON payload instead of XML.

Similarly, the POST method is essentially equivalent to an XML import, but requiring a JSON payload instead of XML.

The PATCH method is interesting, because it offers the ability to change just one property of an object. You do this by providing only the portion of the JSON object schema that corresponds to the property you wish to change.

For example, if you wanted to change the queue of an SCRI object, you could use the PATCH method and provide the following JSON in the body of the request. As far as I can tell, this is the minimal JSON payload sufficient to change the queue property.

{
  "data" : {
    "scri" : {
      "general_attributes" : {
        "queue" : "NEW_QUEUE"
      }
    }
  }
}

The remainder of the JSON object schema is irrelevant and can be omitted. When using the PATCH method, the properties type, name, and path must be omitted.

If you want to move or duplicate an object, there are also dedicated API endpoints for these operations.

Operation	HTTP method & AE REST API endpoint	Body
Move	PATCH /{client_id}/objects/{object_name}/move	{ "target_path": "FOLDER/SUBFOLDER" }
Duplicate	​POST /{client_id}​/objects/{object_name}/duplicate	{ "name": "NEW_OBJECT_NAME", "title": "New object description", "path": "FOLDER/SUBFOLDER" }
Rename	?	?

There is currently no way to rename an existing object, other than exporting, deleting, and then re-importing the object.

Update: APIs for renaming objects are coming in a future relese. See @Martin Uferbach’s comment, below.

[Michael A. Lowry]

The Open API 3.0 swagger.json file for the AE REST API includes many examples of AE object JSON payloads.

I've attached a ZIP file containing these examples as separate files categorized by method (GET, PUT, & PATCH).

Attachment(s)

AE JSON schema examples.zip   53 KB 1 version

[SIVANESAN SIVAKUMAR]

Hi Team,

I want to execute job/job plan outside uc4 via rest api . Can i get some
examples for that ?

On Tue, Mar 5, 2024 at 3:04 PM Michael A. Lowry via Broadcom <
[e-mail]> wrote:

> Automation Engine version 24 introduces substantial updates to the AE REST
> API. Most notably, v24 adds the ability to create, read, update, and...
> -posted to the "Automic Workload Automation" community
> [image: Broadcom] <https: community.broadcom.com="">
> Automic Workload Automation
> <https: community.broadcom.com/communities/community-home/digestviewer?communitykey="2e1b01c9-f310-4635-829f-aead2f6587c4">
> Post New Message
> <[e-mail]>
> AE v24 REST API
> <https: community.broadcom.com/discussion/ae-v24-rest-api#bm6f35e1ea-b927-49bb-8a25-a158f1d17604="">
> Reply to Group
> <broadco[e-mail]?subject=re:+ae+v24+rest+api> Reply
> to Sender
> <https: community.broadcom.com/communities/all-discussions/postreply?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4&SenderKey=4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
> [image: Michael A. Lowry]
> <https: community.broadcom.com/network/members/profile?userkey="4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
> Mar 5, 2024 4:35 AM
> Michael A. Lowry
> <https: community.broadcom.com/network/members/profile?userkey="4cbb3ea7-a3e4-473c-8b9b-3019a08d286c">
>
> Automation Engine version 24 introduces substantial updates to the AE REST
> API.
>
> Most notably, v24 adds the ability to create, read, update, and delete
> <https: en.wikipedia.org/wiki/create,_read,_update_and_delete=""> objects.
> The documentation page Using the AR REST API
> <https: docs.automic.com/documentation/webhelp/english/all/components/docu/24.0/automic%20automation%20guides/content/rest_api/ae_rest_api_using.htm="">
> provides examples for many things, but not these "CRUD" operations. I did
> some basic tests to figure out how it works.
> *Operation*
> *HTTP method & AE REST API endpoint* *Body*
> Create
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post="">
> ​*POST* /{client_id}​/objects
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post=""> Complete
> JSON object definition
> Read *GET* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/get="">
> NA
> Update *PATCH* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/patch=""> Partial
> JSON object definition. Omit *type*, *name*, and *path *properties.
> Delete *DELETE* /{client_id}/objects/{object_name}
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/delete="">
> NA
>
> The GET method is essentially equivalent to an XML export, with providing
> a JSON payload instead of XML.
>
> Similarly, the POST method is essentially equivalent to an XML import, but
> requiring JSON instead of XML as the payload.
>
> The PATCH method is interesting, because it offers the ability to change *just
> one property* of an object. You do this by providing only the portion of
> the JSON object schema that corresponds to the property you wish to change.
>
> For example, if you wanted to change the queue of an SCRI object, you can
> use the PATCH method and provide the following JSON in the body of the
> request.
> { "total" : 1, "data" : { "scri" : { "general_attributes" : { "queue" :
> "NEW_QUEUE" } } } }
>
> The remainder of the JSON object schema is irrelevant and can be omitted.
> When using the PATCH method, the properties *type,* *name, *and *path*
> must be omitted. It is not possible to change the type of an existing
> objects.
>
> If you want to move or duplicate an object, there are dedicated API
> endpoints for these operations.
> *Operation*
> *HTTP method & AE REST API endpoint* *Body*
> Move *PATCH* /{client_id}/objects/{object_name}/move
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/moveobject_1=""> {
> "target_path": "FOLDER/SUBFOLDER" }
> Duplicate
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/post="">
> ​*POST* /{client_id}​/objects/{object_name}/duplicate
> <https: docs.automic.com/documentation/webhelp/english/aa/all/docu/24.0/rest%20api/automation.engine/index.html#/object/duplicate=""> {
> "name": "NEW_OBJECT_NAME", "title": "New object description", "path":
> "FOLDER/SUBFOLDER" }
> Rename ?
> ?
>
> I have not found a way to rename an existing object using the AE REST API
> (other than exporting, deleting, and importing).
> *Reply to Group Online
> <https: community.broadcom.com/communities/all-discussions/postreply?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">*
> *Reply to Group via Email
> <broadco[e-mail]?subject=re:+ae+v24+rest+api>*
> *View Thread
> <https: community.broadcom.com/discussion/ae-v24-rest-api#bm6f35e1ea-b927-49bb-8a25-a158f1d17604="">*
> *Recommend
> <https: community.broadcom.com:443/discussion/ae-v24-rest-api?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&cmd=rate&cmdarg=add#bm6f35e1ea-b927-49bb-8a25-a158f1d17604">*
> *Forward
> <https: community.broadcom.com/communities/all-discussions/forwardmessages?messagekey="6f35e1ea-b927-49bb-8a25-a158f1d17604&ListKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">*
> *Flag as Inappropriate
> <https: community.broadcom.com/discussion/ae-v24-rest-api?markappropriate="6f35e1ea-b927-49bb-8a25-a158f1d17604#bm6f35e1ea-b927-49bb-8a25-a158f1d17604">*
>
>
>
>
> You are subscribed to "Automic Workload Automation" as
> [e-mail]. To change your subscriptions, go to My
> Subscriptions
> <http: community.broadcom.com/preferences?section="Subscriptions">. To
> unsubscribe from this community discussion, go to Unsubscribe
> <http: community.broadcom.com/higherlogic/egroups/unsubscribe.aspx?userkey="bbc24d99-5ad5-4b6f-bbc3-8eab5b500688&sKey=KeyRemoved&GroupKey=7e4de604-f950-4e81-9d19-4e72b8898fb4">.
>
>
> Copyright © 2005-2023 Broadcom. All Rights Reserved. The term "Broadcom"
> refers to Broadcom Inc. and/or its subsidiaries.
>
> Hosted by Higher Logic, LLC on the behalf of Broadcom - Privacy Policy
> <https: www.broadcom.com/company/legal/privacy-policy=""> | Cookie Policy
> <https: www.higherlogic.com/legal/privacy=""> | Supply Chain Transparency
> <https: www.broadcom.com/company/citizenship/governance-and-ethics#supply="">
> | Terms of Use <http: termsandconditions="">
>


--
Thanks & Regards,
Sivanesan
9094570061

[Michael A. Lowry]

Take a look at the POST /{client_id}/executions endpoint.

[Martin Uferbach]

With V24.0 the following renaming action is supported: https://docs.automic.com/documentation/webhelp/english/AA/24.0/DOCU/24.0/REST%20API/Automation.Engine/index.html?overrideUrls=../Automation.Engine/swagger.json,../Continuous.Delivery.Automation/swagger.json,../Analytics/swagger.json,../Infrastructure.Manager/swagger.json#/system%20agents/rename

But this is pure renaming without considering "search for use" dependencies that will follow in future releases.

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------

[Michael A. Lowry]

Hi @Martin Uferbach. Thanks for the reply.

The POST /{client_id}/system/agents/{object_name}/rename endpoint appears to be limited to renaming agents. Is there a way to rename other object types? (Perhaps that too will come in a later release.)

[Martin Uferbach]

Hi @Michael A. Lowry, unfortunately this is the only one at the moment. Indeed, it's more of an agent management endpoint than a general object renaming one. As renaming used objects most likely a complex "search for use" challenge is involved we need to consider when providing a general renaming functionality. Yes, such a powerful renaming functionality via REST API is planned for future release.

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------

[Joel Wiesmann]

Hi @Martin Uferbach

So the REST implementation is completely independant of the JAVA API? I mean, basically it could be implemented like a wrapper/converter.

Regards
Joel

------------------------------
☎️ Swisscom Automation Engineer & 🧙 PE Membership Creator

Automic Kurse, Tutorials, Tools und mehr auf:
https://membership.philippelmer.com/
Zwei Wochen kostenlos testen!
------------------------------

[Michael A. Lowry]

Hi @Joel Wiesmann.

The AE REST Process is implemented in Java. It might be performing some actions via the AE Java API, but a DB trace also reveals plenty of direct DB activity.

[Martin Uferbach]

Hi @Joel Wiesmann, 

Yes, the two interfaces JavaAPI and AE REST API are basically completely separated/decoupled - both code-wise and business case-wise (in other words, the AE REST API is no "copy" of the JavaAPI providing exactly the same just in a different way).

The goal is to provide a modern state-of-the-art interface via AE REST API that offers at some point in time in the future an equal functional range as the JavaAPI that fits today's needs. At the moment there are no plans/no ETA to replace/sunset the JavaAPI. 

The functional range of the AE REST API is successively extended/enriched version by version.

Kind regards,

Martin 

------------------------------
Product Owner for Automic Automation
Broadcom
Austria
------------------------------