Hello Marcel and all, thanks for the detailed reply to Jan's email. My few notes on the REST API are below; I would also point out https://issues.apache.org/jira/browse/ACE-151 which I forgot to mention to him before.
On 4 December 2011 23:37, Marcel Offermans <marcel.offerm...@luminis.nl> wrote: <snip> >> 1. PUT >> Our vision is that by putting a new resource to the OBR, there >> would be a decision, whether it is or it isn't a bundle. If it is another >> file, >> store it only in the OBR. If it is a bundle, perform the versioning according >> the last version of the bundle in the OBR first, then store it. This should >> happen all the time and thus, we could have the consistent list of all the >> versions of the bundle, that were uploaded in time. Naturally, if there is no >> another version, no versioning is performed. > > If you look at the definition of a REST API then the semantics for PUT are to > always store (and replace) the exact resource that you specified, so I would > not want to deviate from that unless we have a really good reason. We are > however free to add a POST command that uses semantic versioning. I agree, we should use POST for that. >> The problem is, that only the method put(String fileName, InputStream >> data) is present so far, the client decides the filename. If there is a file >> with >> this name in the OBR (which is the case by different bundle versions) it >> would >> be overwritten. > > We are free to extend our API. Would a VersionedBundleStore extends BundleStore interface be a reasonable solution? I guess we should not modify the BundleStore since it is standardized. >> To let the OBR API backward compatible and still take advance >> from the versioning, the client have to manually add the the version suffix >> to the >> filename, but it doesn't know, whether the version in the manifest is really >> correct, since no semantic versioning was performed yet. > > Right now we assume the client has correctly done semantic versioning. Most > of the time, he will have to do that by hand, but there are other tools > surfacing that help (BndTools now allows this). This however is at odds with our intention, which is to integrate semantic versioning seamlessly into ACE to ensure the bundles are versioned correctly in its repository, regardless of whether client does use semantic versioning. What Jan points at is that the integration brings however the need for the client to obtain the generated version and possibly the final filename of the stored bundle. >> We propose to add another method to the OBR servlet like >> dryRun(InputStream data), that perform the versioning on the uploaded bundle >> but doesn't store it to the OBR, only returns in the HTTP header the info, >> whether >> there is another version and if so, also the corrected version of the >> uploaded >> bundle. Then the client constructs the filename and calls the common put >> method. > > Let me make a counter-proposal here to add a POST method that will do the > upload, then modify the bundle (if there are existing versions in the OBR of > this same bundle) and finally either redirect or return the proper URL of the > versioned bundle. Redirect looks like a reasonable solution; my question (maybe due to lack of experience) is: will the client interpret it as we want it, ie "this is the URI -> filename under which my bundle is stored, I need to remember it"? >> 2. GET >> Typically I like to get the latest version of the bundle, that is in the >> repository. >> We can use the present get(filename) method, but we have to know the >> filename. >> listBundles(String symbolicName) would do the work, possibly by inspecting >> the repository.xml. > > The current OBR spec indeed assumes that you first GET the repository.xml, > parse that and based on the information inside that file, make up your mind > about what exact bundle (or artifact) you want. > > On top of that, I could live with an optional query mechanism that allows you > to do things like: > > GET /obr/?bsn=org.apache.felix.cm - to return the highest version of a bundle > with the specified symbolic name > GET /obr/?vsn=org.apache.felix.cm&v=[1.0,2.0) - same, but highest version > within the given range > GET /obr/?vsn=org.apache.felix.cm&v=[1.0,2.0)&lowest - same, but lowest > version within the given range > > or even, some kind of query that will return a list or subset (in which case > it might actually make sense to either return just URLs or a filtered > repository.xml) Shouldn't we rather have GET /obr/artefact/org.apache.felix.cm GET /obr/artefact/org.apache.felix.cm&v=[1.0,2.0) etc? Premek -- Premek Brada (Ing et MSc, PhD) Head of Software Engineering and Information Systems Section Department of Computer Science and Engineering University of West Bohemia in Pilsen, CZ << brada at kiv.zcu.cz | www.kiv.zcu.cz/~brada/ | +420-377-63-2435 >>
