CounterSoft User Forums

The schema documentation page at has been promising docs soon since 3.5 was released. Can you offer an update on when we might actually get those docs? The extant API docs are painfully incomplete, and a good schema doc would make a nice dent in that problem.

What are you after exactly? (what are you trying to achieve?)

---

First of all, the forum stripped my URL; it should be: http://api.countersoft.com/Schema.aspx. There's been a "coming soon" message there since you initially posted the docs.

For the schema docs, I'm looking for, well, documentation of the XML schema used by the web service. As it is now, it's a tedious game of trial and error to figure out what XML Gemini is expecting of the various service methods, and what data to include with the XML in what format. Ideally, the schema docs will come with an update to the existing docs that includes information about which data are or aren't required, and what the behavior of the methods is in the various use-cases. As a couple of examples of my own problems caused by this in the past:

http://community.countersoft.com/forums/thread/11630.aspx
http://community.countersoft.com/forums/thread/11501.aspx

And more recent examples of other questions that would have been answered by such docs:

http://community.countersoft.com/forums/thread/14529.aspx
http://community.countersoft.com/forums/thread/13876.aspx

I know there's the Java sample code, but the last time I looked at it after it was first released, the code by itself proved to be of little help since it pieces together the XML on-the-fly, and not being a Java programmer, it's not exactly convenient to try to run it and step through it to see what's happening. Straightforward, complete, language-neutral docs would be far more valuable.

Bob, we have updated the api site.
Please have a look and let us know your feedback.

http://api.countersoft.com/

---

That's a helpful start in that now we can see the base items without having to make queries to pull down examples. That will definitely save some time.

What's still missing are details of how everything ties together. Let's take creating issues as an example. Say I want to create a new issue that has a particular user assigned to it. Looking at the docs, it looks like I need to call /api/issues.ashx/issues or /api/issues.ashx/issuespartial. Both of these are looking for an IssueEN block. So now I can go to the new schema docs and see what IssueEN looks like - which is great. But how do I specify the assignee? I see these elements which appear to be related:

<IssueResources />
<IssueResourcesUserName />
<IssueResourcesFullName />
<IssueResourcesID />

So with that information, how do I proceed? Are these supposed to contain the data about my desired assignee, or do they contain other elements which in turn contain the actual data? If so, what are those elements? How do things differ if I want to assign multiple users versus just one? Are any of these optional, such that they can be skipped and Gem will fill in the details? To answer these questions requires I go back to pulling existing issues to serve as examples, followed by trial-and-error to see what does or doesn't work. And I must do this recursively, e.g., trying to figure out which of the many fields in IssueResourceEN are actually required to get Gem to do what I want.

To answer the question, I can look at my code where I've already figured all this out. I need to pass something like this:
<IssueResources><IssueResourceEN><UserID>1234</UserID></IssueResourceEN></IssueResources>

So what I'm really looking for is documentation that answers those sorts of questions. Thus, the next logical step in evolving the docs would be to expand each method's description with specifics about what needs to go in and what will come out. Alternatively, expand the schema docs to list next to each item the methods that it's used with, when it can/should be used, whether it's optional or mandatory with those methods, what the input data should look like, and what the output data will look like.

Does that make sense?

Makes sense, thanks for the feedback we will try and imporve the docs further.

---