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] _______________________________________________
