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
