ace-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From pa...@apache.org
Subject svn commit: r1367077 - /ace/site/trunk/content/user-doc/restapi.mdtext
Date Mon, 30 Jul 2012 13:15:47 GMT
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



Mime
View raw message