> > For example, WADL for the human readable docs at http://[matterhorn > server]/workflow/docs there is a WADL at http://[matterhorn > server]/workflow/?_wadl&_type=xml
I'm sorry, Josh, but that does not work for me in a Matterhorn 1.2... 2011/9/14 Josh Holtzman <[email protected]> > The docs are the human-readable format of the REST API. They were designed > to help developers quickly and easily integrate. It sounds like you want a > more formal description of these services, which we povide in the form of > Web Application Description Language (WADL): > > http://en.wikipedia.org/wiki/Web_Application_Description_Language > > For example, WADL for the human readable docs at http://[matterhorn > server]/workflow/docs there is a WADL at http://[matterhorn > server]/workflow/?_wadl&_type=xml > > In the docs, search for the phrase "Returned entity schema" and click the > link next to it: this provides the XML schema of the object returned by > this endpoint. > > I understand that coming into the project at this point can be difficult. > But you should not have to read through the code to integrate with > Matterhorn's REST endpoints. If the endpoints are not properly documented, > or are confusing, please file bugs and if possible, suggest language to make > them clearer. > > That said, if you're interested in putting together diagrams and other > forms of documentation, I'm sure that would be appreciated! > > Josh > > On Sep 13, 2011, at 11:05 AM, Pawel Fic wrote: > > > Hi, > > > > How about creating [or publishing] on Matterhorns Wiki UML Diagrams for > Matterhorn and some additional spec. > > > > You know, it you are familiar with Matterhorn everything may be very > simple. If you are new to Matterhorn - hours of reading the source code may > lead you to a conclusion: it chaos. > > > > Spec and documentation will help to maintain the project. > > > > I think good start would be System context diagram and Data flow diagram > (to understand Matterhorn): > > http://en.wikipedia.org/wiki/System_context_diagram > > http://en.wikipedia.org/wiki/Data_flow_diagram > > > > But of course -- to do it right we may start from the beginning (like Use > cases). > > http://en.wikipedia.org/wiki/Use_case_diagram > > > > > > > > > > and [I need] spec for REST endpoint that are responsible for integrating > capture agent with Matterhorn: > > 1. Capture Agent Admin REST Endpoint > > 2. Ingest REST Endpoint > > 3. Scheduler REST Endpoint > > > > Current spec (Docs) are not sufficient. Since it is generated > automatically it is exposed to rapid changes. Engineer changes "calendar" to > "recordings" and capture agents all over the world needs to be updated. > > I don't mind if the change was necessary, but if this was only a cosmetic > change. Because it looked better. > > With new approach (spec on Matterhorn's Wiki) engineer will have to > update the spec on Wiki first and he will be aware that this change affects > other parts of the system. > > > > Other than this - docs are not sufficient. And then they cannot be used > by third party software. Also engineers who are new to the project, may not > understand why: /capture-admin/recordings provides them with empty list > instead a list of recordings just like the spec says [Return all registered > recordings and their state]. > > > > > > do you think this is a good idea ? > > > > what are your thought on use cases / data flow diagrams ? > > > > what are your thought on spec of crucial endpoints. > > > > > > --the benefits would be that we would know what the code is actually > doing. Right now, I think only the people who wrote a particular piece of > code actually are aware how it supposed to behave. > > > > -Pawel > > > > > > > > _______________________________________________ > > Matterhorn mailing list > > [email protected] > > http://lists.opencastproject.org/mailman/listinfo/matterhorn > > > > > > To unsubscribe please email > > [email protected] > > _______________________________________________ > > _______________________________________________ > Matterhorn mailing list > [email protected] > http://lists.opencastproject.org/mailman/listinfo/matterhorn > > > To unsubscribe please email > [email protected] > _______________________________________________ >
_______________________________________________ Matterhorn mailing list [email protected] http://lists.opencastproject.org/mailman/listinfo/matterhorn To unsubscribe please email [email protected] _______________________________________________
