Hi Pawel, I agree with most of your thoughts. However I'd like to reply to this one:
forget freezing API (how can somebody even mention this at this stage of > development) Well, I would say "how can the API *not* be frozen at this stage of development?". I mean, Matterhorn is not in a beta version. It's 1.2. One would expect some well-developed APIs at this stage, it's not like we have not tested the system and we don't know what we want it to do and how. Now, the CA function is clear and well-defined. It has been for a long time. Its functions can be summed up in a quite short list: -> Get State (what is state, meaning of each possible states) -> Set State (which states can be set directly, which ones not) -> Get recording devices (capabilities) -> Get configuration -> Set configuration (which keys can be set, which can't) -> Schedule recordings (this done via calendar polling) -> Start/Stop (Pause?) recordings (scheduled or perhaps not) -> Get recordings We could argue if an "Ingest" endpoint to tell the agent to ingest some recording into some core is necessary. In fact, we could argue if some MORE functions are necessary. But the basic functionality has been like this for a LONG time. The problem is that an comprehensive, standard and well-documented API has never been well defined and developers may not understand clearly what a parameter is for or what is the meaning of a certain endpoint. That's exactly the problem. It's not that the CA functioning has changed so much that the API couldn't stay the same --that's not true. As many internal changes as the CA may have had, they haven't changed the way that the CA interacts with the core, and therefore they shouldn't affect the API. This only shows that the decissions were not made at the right times, and now we are forced to fix the problems that should have been addressed long ago, when the CA was still being designed. Otherwise, you cannot talk about stability. Stability is about being permanent, about leaving things unchanged and working as expected for long time. If I have a very changeable API nobody could even say it's "stable" at all, no matter how well documented and visible those changes are. Best regards Rubén 2011/9/13 Pawel Fic <[email protected]> > I think we need to focus on thread subject: Stable and documented API for > third party software to communicate with Matterhorn. > Forget version numbering, forget backward compatibility, forget freezing > API (how can somebody even mention this at this stage of development). > Forget about creating mechanism to check the REST calls (impossible, and > maintaining it will slow down the development) - just create a spec and > stick to it. Once somebody will change "/capabilities" to "/configuration" > users will soon notice it and complain [if nobody will notice than who > cares?]. Now users are confused - is "/configuration" a bug or is it how it > supposed to be and "/capabilities" where bad? [BTW: I am the users - LOL] > > I could use something stable and documented in this project. > > > Here are two simple examples: > > Example 1: > ============= > I have a video content servers with 200 of videos. They cannot be searched, > they are just stored. > I would like to upload them to Matterhorn. > > I open Matterhorn REST endpoint docs and read: > > <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< > For ingesting media package I should use: > POST /addZippedMediaPackage > I have to provide workflowDefinitionId, workflowInstanceId and BODY. > Well, those are documented: > The workflow definition ID to run on this mediapackage, > The workflow instance ID to associate with this zipped mediapackage > The compressed (application/zip) media package file > <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< > > There is no way I can use this HTTP call without going deep into > Matterhorn's implementation details. > But source code is going to be changed [I have to assume my work will be > ruined]! > > > Example 2: > ============= > I have capture device (embeded device - no java). But I have the C++ CURL > library. > It is used to record an engineering meetings and CEO's speech. > Engineering meetings - who would ever like to listen to those - 320x240, > 8bit 22MHz. > CEO's speech must be captured in HD, stereo and 44KHz audio. > > I would like to register my capture agent with appropriate capabilites so > when I shedule a recording there is a checkbox saying "capture in HD". > > Here is a documented REST endpoint saying almost nothing: > > <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< > POST /agents/{name}/configuration > Set the configuration of a given capture agent, registering it if it does > not exist > name: The name of a given capture agent > Configuration: An XML representation of the capabilities, as specified in > http://java.sun.com/dtd/properties.dtd (friendly names as keys, device > locations as their corresponding values) > <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< > > I am not even sure if those agent's capabilities are ever used somewhere, > and now they are called "configuration" (!). > > > > SOLUTION > ============ > Somebody must write down and approve a set of HTTP calls that supposed to > be used with Matterhorn. [I think I am willing to help] > Forget Java/Forget source code/Forget classes. Write a spec and people > developing the code must stick to the document. > There should be a description saying how to use it, and what are the > parameters. > Descriptions like: "state" - agent's state are not sufficient. > But this document must mean something. > > Changing: > calendar/recordings/<agentid> > to: > recordings/?agentid=<agentid>&seriesId=<series> > > is simple. > Changing it to: > calendar/recordings/<agentid>[?seriesId=<series>] > > is also simple, but does not ruins existing capture agents. And then > Capture Agents will not stay completely useless behind rest of the server. > > Updating 5% of the code is fine. Updating 60% is rewriting it all from > scratch. > > And frustrating if you are aware that this is something you will have to > repeat every couple of months, and not knowing that what you done is > correct. Maybe "addZippedMediaPackage" is temporarty endpoint? > > I was told that using REST endpoints allows me to develop Capture Agent. I > can see that is was designed this way. Now I have a feeling that REST > endpoints are just consequences of using some kind of Java mechanisms and > they are going to change instantly, and I can't use them. > > > > > This work will may take a week of two. It will be monotonous. Probably the > document will not cover everything, but there will be questions asked. Like: > "what is mediapackage", "what is recording", what is "workflow", what is > "workflowid". > > > ------- > This documentation must be preceded with introduction saying: "what is > workflow". How video / slides / texts are handled by Matterhorn. Maybe a lot > of this already can be found on Matterhorn Development Wiki, but I have not > found the chapter saying "Data flow diagram". I looked at "Integration > Scenarios" (sounded interesting). > > I think REST endpoints supposed to be a part of "Integration Scenarios". > Using REST endpoints I am able to develop my own scheduler, my own admin > tools. > Having REST endpoints documented I can always ask about "what should I do > to schedule a recording", > "how can I registers capture agent with such capabilities" - and so on. > > Without this spec I have to install Matterhorn, browse the sources or just > ask post a question hoping that somebody will answer me, and my code will be > working with current version. > > -Pawel > > > _______________________________________________ > Matterhorn-users mailing list > [email protected] > http://lists.opencastproject.org/mailman/listinfo/matterhorn-users >
_______________________________________________ Matterhorn-users mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/matterhorn-users
