Introduction

To automate the interaction with ACE, you can use its REST client API. Typical use cases include the tight integration of ACE into your development or automated build process, or the creation of a custom user interface or integration.

This is still a work in progress which you can track in ACE-151.

Overview

Before we dive into the various REST endpoints, let's start with an overview of how all of this works. Everything in ACE is an entity. For example, an artifact or a feature is an entity, but also the association between an artifact and a feature is. Entities have properties and tags. Properties are the "fixed" attributes that make up a specific type of entity. For example a feature has a name and a description. If you know the type of entity, its properties are also known. Tags on the other hand are attributes that a user can freely add and refer to.

The following diagram shows the different entities that ACE knows:

For each entity we will now list and explain the properties:

Artifact

Artifacts contain the metadata for the different types of artifacts that can be provisioned to targets. Artifacts can be bundles, configuration data or any other type you've defined yourself.

• artifactName
• artifactDescription
• url
• mimetype
• processorPid

Since there are different types of artifacts, some properties depend on the actual type.

For bundles:

• Bundle-Name
• Bundle-SymbolicName
• Bundle-Version

For configuration:

• filename

For other types, please consult the documentation about these types (specifically the classes that implement the interfaces in the org.apache.ace.client.repository.helper package).

Artifact2Feature

Associates artifacts to features. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.

• leftEndpoint
• rightEndpoint
• leftCardinality — defaults to 1
• rightCardinality — defaults to 1

Feature

A feature is a grouping mechanism for artifacts. It is commonly used to group together a set of artifacts that together represent some kind of feature to the application.

• name
• description

Feature2Distribution

Associates features to distributions. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.

• leftEndpoint
• rightEndpoint
• leftCardinality — defaults to 1
• rightCardinality — defaults to 1

Distribution

A feature is a grouping mechanism for features. It is commonly used to group together a set of features that together represent some kind of distribution. Distributions are the things you can associate with targets, so you can look at them as the licensable configurations of your software.

• name
• description

Distribution2Target

Associates distributions to targets. Associations have a left and right hand side. Both can be expressed as filter conditions, and both have a cardinality.

• leftEndpoint
• rightEndpoint
• leftCardinality — defaults to 1
• rightCardinality — defaults to 1

Target

A target receives the artifacts you provision to it. Most of the time, a target is an OSGi container and provisioning means you'll actually install the artifacts in the container, but there can be other types of targets (non-OSGi containers, or something completely different).

• id
• autoapprove

A target also has specific state (see below for how that is returned):

• registrationState — Unregistered, Registered
• provisioningState — Idle, InProgress, OK, Failed
• storeState — New, Unapproved, Approved
• currentVersion
• isRegistered
• needsApproval
• autoApprove
• artifactsFromShop
• artifactsFromDeployment
• lastInstallSuccess

Checkout and commit

Similar to the web based UI, this API also works with the concept of checking out a copy to a local working area, altering it in that working area and then committing it back to the server.

POST /work

Creates a working copy for you, with its own ID, and redirects you to it. (For the contents of this working copy, see below.)

Response:

• 302 /work/ID

DELETE /work/ID

Deletes the working copy. Signals you're done with it, without transferring the data back to the server.

POST /work/ID

Sets the working copy to be the current version. We keep track of whether you have based your copy on, and will reject the update if it is no longer the latest.

Response:

• 200
• 409

Repositories and objects

Now you have a working copy, you can start working with it.

GET /work/ID

Gets you a list of all repositories you can use. Should return: ["artifact", "feature", "distribution", "target", "artifact2feature", "feature2distribution", "distribution2target"]

GET /work/ID/feature

Lists all feature IDs in the feature repository.

POST /work/ID/feature

Creates a new feature. In the post body, you can specify attributes and tags, for example: {attributes: {key: "value"}, tags: {key: "value"}}.

Response:

• 302 /work/ID/feature/FID
• 400

GET /work/ID/feature/FID

Returns a representation of the object, for example: {attributes: {key: "value"}, tags: {key: "value"}}. If you ask for a target, you will also get its state, so the result will be in the form: {attributes: {key: "value"}, tags: {key: "value"}, state: {key: "value"}}.

PUT /work/ID/feature/FID

Updates the object with the JSON data you supply.

Response:

• 200
• 400
• 404

DELETE /work/ID/feature/FID

Deletes the object.

Response:

• 200
• 404