On Sep 14, 2011, at 2:22 PM, Pawel Fic wrote: > Thanks Josh. It helped me a bit. I searched the source code to find > /capture-admin/agents.xml endpoint. > > I first browsed: > /docs.html?path=/capture-admin > but I have not found it. Then searched the code. > Now I opened: > /capture-admin/?_wadl&_type=xml > and there is is. > It is up to date, and /docs.html?path=/capture-admin is not. >
OK, that's good to to know. If you haven't already, please file a bug so we can fix the capture-admin REST docs. > > ------- > Josh, I think you are one of the crutial people in this project, so I address > this one to you probably: > > 1.] > Assumming that I have some engineering time, that I want to spend on > Matterhorn [for example: adding an option to remove a servies from Admin > Tools]. > -Where can I find information that will actually allow me to add the changes > and commit the code. > First of all, I'm glad that you're considering this! Now to answer your questions: If you want to make changes, you can look at the code, the wiki, ask specific questions here and ask on IRC. This is a "developers" list, so don't be afraid to ask very specific, technical questions. The more specific you can be, the more others can help you. When you want to have your code committed, you need to work with the committers. You can attach a patch to a Jira ticket or attach it to a code review in Crucible. If the committers are satisfied that the code meets their standards (whatever that might mean), they will commit it. If not, they will work with you to help bring it into alignment. If you go through this process a few times, you'll probably become a committer. See http://opencast.jira.com/wiki/x/BQJeAQ > > 2.] > Is there a place where I can read more about tricks like: > /capture-admin/?_wadl&_type=xml > Unfortunately, these kinds of things are scattered all over the wiki and the email archives. Cleaning up our documentation seems to be an endless chore, and one that could always use more eyes/hands/minds. If this is an area you want to help with, I know that Chis, Michelle, Nils, and others who have worked intensively on the wiki would love your help. > > 3.] > I have a feeling that current spec is not sufficient. I actually have to > browse the source code. Do you agree with me, or is there a place where I can > read about it, and learn that it is sufficient. > As a developer looking to integrate with Matterhorn, only you can say whether the documentation (Wiki, REST docs, Javadocs) is sufficient for your needs. It sounds like you're not getting everything you need. So the best thing you can do for the project and for yourself is to work with the developers on this list to produce the documents you need (entity relationships, sequence diagrams, etc). > > 4.] > I want to register my capture agent using /capture-admin/agent rest endpoint. > I have to pass XML file there with bunch of tags inside. Some are simple > like <name>. > > Where can I learn about it that capture agent's name cannot contain spaces. I didn't know that this was a limitation. It should be in the REST docs. It's either a documentation bug, or an implementation bug. Please file this in Jira. > Where can I learn about the content of "<capabilities>" > It should be in the XSD in the REST docs. If there is no schema available there, please file a feature request. > > 5.] > If this spec is necesseary than I am interested in builing it. This probablty > be a large HTML file like: > http://v4l2spec.bytesex.org/spec-single/v4l2.html In an agile project, I've found that storing specs outside of the code base just leads to outdated specs. If at all possible, I'd prefer augmenting the REST docs with whatever is missing. That way, the documentation is inline with the endpoint code, so it's easier to keep things in sync. > > I will need help with editing it (I could use a native speaker), explaining > the details and approval from Matterhorn's community that this API will be > respected. Cool! I'm sure people here will help. > That nobody will change REST endpoint without earlier aproving change to the > API, and updateing the document. This is where the committers come in. If someone wants to change the API, they'll make a request on list. Anyone can vote, but the committers votes are "binding". Any -1 from a committer means that the change can not be committed. Capture admin, scheduling, and ingest are particularly sensitive areas, since these are the main integration points for people like you, so they shouldn't change at this point without a very good reason, and a lot of warning. > > Please: do not say "if you're interested in putting together diagrams and > other forms of documentation, I'm sure that would be appreciated!" > > Explain me how can I start doing this? > You want me to create an HTML file and send it to you - you will edit it and > put it on Matterhorn wiki pages? I cannot do it right now by myself. > It's probably best to start with a self-contained project, rather than trying to document all of Matterhorn. How about looking into the contents of <capabilities>? Can anyone point Pawel to the Java representation of these capabilities? Is the Java class JAXB annotated? Can we expose the XSD via the capture agent REST docs? Thanks, Josh > -Pawel > > --- On Wed, 9/14/11, Josh Holtzman <[email protected]> wrote: > >> From: Josh Holtzman <[email protected]> >> Subject: Re: [Opencast Matterhorn] Matterhorn's design >> To: "Opencast Matterhorn" <[email protected]> >> Date: Wednesday, September 14, 2011, 4:06 PM >> 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 >> > > _______________________________________________ > 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] _______________________________________________
