You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ace.apache.org by pa...@apache.org on 2012/07/30 15:15:47 UTC
svn commit: r1367077 - /ace/site/trunk/content/user-doc/restapi.mdtext
Author: paulb
Date: Mon Jul 30 13:15:47 2012
New Revision: 1367077
URL: http://svn.apache.org/viewvc?rev=1367077&view=rev
Log:
Added rest api documentation
Added:
ace/site/trunk/content/user-doc/restapi.mdtext (with props)
Added: ace/site/trunk/content/user-doc/restapi.mdtext
URL: http://svn.apache.org/viewvc/ace/site/trunk/content/user-doc/restapi.mdtext?rev=1367077&view=auto
==============================================================================
--- ace/site/trunk/content/user-doc/restapi.mdtext (added)
+++ ace/site/trunk/content/user-doc/restapi.mdtext Mon Jul 30 13:15:47 2012
@@ -0,0 +1,193 @@
+Title: Client REST API
+Notice: Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+ .
+ http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+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:
+![alt text][1]
+
+
+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
+
+
+ [1]: https://cwiki.apache.org/confluence/download/attachments/27822075/entities.png?version=1&modificationDate=1311923466000
\ No newline at end of file
Propchange: ace/site/trunk/content/user-doc/restapi.mdtext
------------------------------------------------------------------------------
svn:eol-style = native