ace-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Angelo van der Sijpt (JIRA)" <j...@apache.org>
Subject [jira] [Issue Comment Edited] (ACE-151) Create a REST client API
Date Thu, 23 Jun 2011 10:36:47 GMT

    [ https://issues.apache.org/jira/browse/ACE-151?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13053724#comment-13053724
] 

Angelo van der Sijpt edited comment on ACE-151 at 6/23/11 10:36 AM:
--------------------------------------------------------------------

[~karlpauls] and I took the API proposal, and expanded on it a bit; hence, there may be overlap
between this, and the existing proposal. The highlights,
- we rename session to 'checkout' in the SCM sense.
- associations have their own endpoints, which allows filters, and can be used both in a simplified
way, and using full-fledged filters,
- individual tags and attributes cannot be addressed.


Checkout & commit
-----------------
A git-like mechanism, which gets you a 'working copy', which you alter, and can post back.
This working copy is all you have, obviating the need for checkout/commit/revert commands.
The relevant interactions,
GET ace/clients
  Gets all available versions
  [1,2,3,4,5]
GET ace/clients/latest
  Returns the latest version (perhaps a redirect?)
  302 ace/clients/5
POST ace/clients/tmp "5"
  You post the version you want to base the working copy on. This creates a working copy for
you, with its own ID, and redirects you to it. (For the contents of this working copy, see
below.)
  302 ace/clients/tmp/9876
DELETE ace/clients/tmp/9876
  Deletes the working copy; signals you're done with it, without transferring the data.
POST ace/clients "ace/clients/tmp/9876"
  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.
  200 or 409


Repositories & objects
----------------------
Now you have a working copy, you can start inspecting it.

GET ace/clients/tmp/9876
  Gets you a list of all repositories you can use.
  ["artifacts", "features", "distributions", "targets", "artifact2feature", "feature2distribution",
"distribution2target"]

For each repository, you can list it, and post to it.
GET ace/clients/tmp/9876/features
  Gets you the list of feature IDs (we don't use 'human readable' ones. Also, they are likely
only useful for this checkout.)
  [45, 46, 47]
POST ace/clients/tmp/9876/features
  Creates a new feature. You can post attributes and tags to it: {"attributes": {"key":"value"},
"tags": {"key":"value"}} . The same rules apply as when creating objects with the RepositoryAdmin.
  302 ace/clients/tmp/9876/features/48 or 400

Single objects can be addressed too.
GET ace/clients/tmp/9876/features/46
  Gets you a representation of the object.
  {"attributes": {"key":"value"}, "tags": {"key":"value"}}
PUT ace/clients/tmp/9876/features/46
  Allows you to update the object, by putting the full json representation to it.
  200 (ok) or 404 (doesn't exist) or 400 (rejected json)
DELETE ace/clients/tmp/9876/features/46
  Deletes the given resource.
  200 or 404


Associations
------------
We choose associations to be their own object. We use a slightly simplified version of the
associations used in the RepositoryAdmin: we assume associations to be made between two (or
more) objects, and will represent them as such. 
- In the case of dynamic associations, this can mean the endpoints of the association change.
In fact, it is possible that you create an association, and retrieve it immediately afterwards,
and it looks different; this can happen when you create a dynamic association from a bundle
in version 1.0 to some feature, but there also is a 1.1 available.
- If there are 'smart' associations, e.g. associations that provide a filter for all bundles
which answer to "org.foo.*" with a cardinality greater than one, you will get back a list
of endpoints; you will not be able to get back the filter.

GET ace/clients/tmp/9876/artifact2feature
  Gets you a list of all known associations.
  [1234,1235,1236]
POST ace/clients/tmp/9876/artifact2feature
  Allows you to create a new association, by posting the JSON representation to it. For both
sides of an association, you can either specify the object you want to use on that side, or
a 'filter'.
  - For instance, post {left: "artifact/13", right:"feature/46", type:"dynamic"} to create
a dynamic association between some artifact and some feature; 'dynamic' means that the left
side will be updated to the newest version available automatically.
  - If you post filters, like {leftfilter: "(key=value)", rightfilter: "(&(key=value)(key2>=value2))"},
those will be used for the underlying association without any additional validation. We use
the same LDAP filter that the underlying association objects use.
  - You can mix filters and objects, as long as they don't apply to the same side of an association.
The 'type' you provide will be applied to the side which has the object.
  302 ace/clients/tmp/9876/associations/1237 or 400
  
The list of associations can be filtered,
GET ace/clients/tmp/9876/artifact2feature?left=<uri>&right=<uri>
  Gets you all associations between two given objects; both 'left' and 'right' are optional.

You can address individual associations,
GET ace/clients/tmp/9876/artifact2feature/1235
  Gets a representation of the current state of the association
  200 {{left: ["artifact/13"], right:["feature/46"], leftfilter="(Bundle-SymbolicName=org.foo.bar)",
rightfilter="(name=fortysix)"}}
PUT ace/clients/tmp/9876/artifact2feature/1235
  Works in the same way as creating an association.
DELETE ace/clients/tmp/9876/artifact2feature/1235
  Removes the underlying association.
  200 or 404


      was (Author: angelovds):
    [~karlpauls] and I took the API proposal, and expanded on it a bit. The highlights,
- no more session, but you get a 'checkout'. Authentication is handled using BasicAuthentication,
- associations have their own endpoint, which allows filters,
- individual tags and attributes cannot be addressed.

Identification
--------------
In stead of using getting a session ID, we use BasicAuthentication.

Checkout & commit
-----------------
A git-like mechanism, which gets you a 'working copy', which you alter, and can post back.
The relevant interactions,
GET ace/clients
  Gets all available versions
  [1,2,3,4,5]
GET ace/clients/latest
  Returns the latest version (perhaps a redirect?)
  302 ace/clients/5
POST ace/clients/tmp "5"
  You post the version you want to base the working copy on. This creates a working copy for
you, with its own ID, and redirects you to it. (For the contents of this working copy, see
below.)
  302 ace/clients/tmp/9876
POST ace/clients "ace/clients/tmp/9876"
  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.
  200 or 409


Repositories & objects
----------------------
Now you have a working copy, you can start inspecting it.

GET ace/clients/tmp/9876
  Gets you a list of all repositories you can use.
  ["artifacts", "features", "distributions", "targets", "associations"]

For each repository, you can list it, and post to it.
GET ace/clients/tmp/9876/features
  Gets you the list of feature IDs (we don't use 'human readable' ones. Also, they are likely
only useful for this checkout.)
  [45, 46, 47]
POST ace/clients/tmp/9876/features
  Creates a new feature. You can post attributes and tags to it: {"attributes": {"key":"value"},
"tags": {"key":"value"}} . The same rules apply as when creating objects with the RepositoryAdmin.
  302 ace/clients/tmp/9876/features/48 or 400

Single objects can be addressed too.
GET ace/clients/tmp/9876/features/46
  Gets you a representation of the object.
  {"attributes": {"key":"value"}, "tags": {"key":"value"}}
PUT ace/clients/tmp/9876/features/46
  Allows you to update the object, by putting the full json representation to it.
  200 (ok) or 404 (doesn't exist) or 400 (rejected json)
DELETE ace/clients/tmp/9876/features/46
  Deletes the given resource.
  200 or 404


Associations
------------
We choose associations to be their own object. We use a slightly simplified version of the
associations used in the RepositoryAdmin: we assume associations to be made between two (or
more) objects, and will represent them as such. 
- In the case of dynamic associations, this can mean the endpoints of the association change.
In fact, it is possible that you create an association, and retrieve it immediately afterwards,
and it looks different; this can happen when you create a dynamic association from a bundle
in version 1.0 to some feature, but there also is a 1.1 available.
- If there are 'smart' associations, e.g. associations that provide a filter for all bundles
which answer to "org.foo.*" with a cardinality greater than one, you will get back a list
of endpoints; you will not be able to get back the filter.

GET ace/clients/tmp/9876/associations
  Gets you a list of all known associations.
  [1234,1235,1236]
POST ace/clients/tmp/9876/associations
  Allows you to create a new association, by posting the JSON representation to it, something
like {left: "artifact/13", right:"feature/46", type:"dynamic"} . The 'type' parameters is
an interpreted one, and will be translated to filters in the underlying associations.
  302 ace/clients/tmp/9876/associations/1237 or 400
  
The list of associations can be filtered,
GET ace/clients/tmp/9876/associations?feature=<uri>&artifact=<uri>
  Gets you all associations between two given objects.
GET ace/clients/tmp/9876/associationsassociations?feature=<uri>&artifact
  Gets you all associations between a given object and the 'type' of the other side.
GET ace/clients/tmp/9876/associationsassociations?feature=<uri>
  Gets all associations that involve features
GET ace/clients/tmp/9876/associationsassociations?feature&artifact
  Gets all associations between features and artifacts
GET ace/clients/tmp/9876/associationsassociations?feature
  Gets all associations that have to do with features.

You can address individual associations,
GET ace/clients/tmp/9876/associations/1235
  Gets a representation of the current state of the association
  200 {{left: ["artifact/13"], right:["feature/46"], type:"dynamic"}}
PUT is not allowed; we assume associations to be immutable (at least, for us they are)
DELETE ace/clients/tmp/9876/associations/1235
  Removes the underlying association.
  200 or 404

  
> Create a REST client API
> ------------------------
>
>                 Key: ACE-151
>                 URL: https://issues.apache.org/jira/browse/ACE-151
>             Project: Ace
>          Issue Type: New Feature
>            Reporter: Marcel Offermans
>            Assignee: Marcel Offermans
>
> After some discussion on the mailing list, we agreed that it makes sense to add a REST
based client API to ACE to make it easier to integrate ACE in different environments.
> The main requirement for this API is that it should expose the whole client API (currently
available as OSGi services) using REST. Because each client interacts with the server using
a local checkout, this probably means some means to work on sessions (which might seem like
something that's not done in REST but in this case a session is like a working area that you
create for manipulating its contents and finally commit back to the server and clean up. Authentication
can be added via normal basic authentication, so there's no need to explicitly design that
into the API.
> So an interaction with the server could start somewhat like this:
> POST /ace/client -> sessionid
> This will trigger a basic authentication, which, if it succeeds, will return a session
id. It makes sense to also implicitly do a checkout.
> GET /ace/client/mysessionid/feature -> list of feature id's
> Will return a list of features in the repository.
> PUT /ace/client/mysessionid/feature/MyCustomFeature
> Will create a new feature with a unique id called "MyCustomFeature". Maybe the put will
also contain some (JSON/XML) data to describe the feature.
> In general, we can map all our entities (artifacts, features, distributions and targets)
as well as all our associations (artifact2feature, feature2distribution, distribution2target)
to REST endpoints that are very similar, so:
> /ace/client/<sessionid>
>    /artifact
>    /feature
>    ...
> And for each of those repository objects (as they're called in the code) we can do things
like:
> GET /ace/client/<sessionid>/<repositoryobjecttype>/<objectid>/tag
> To get a list of all tags associated with object "objectid".
> PUT /ace/client/<sessionid>/<repositoryobjecttype>/<objectid>/tag/description
"This is a description."
> To set/replace the description tag.
> Finally, for the 'checkout', 'revert' and 'commit' commands, we could do something like
this:
> GET /ace/client/<sessionid>/{commit,revert,update}
> Which will return success or failure.

--
This message is automatically generated by JIRA.
For more information on JIRA, see: http://www.atlassian.com/software/jira

        

Mime
View raw message