Remember the early days of learning about computer programming? I remember reading magazines like Compute & Dr. Dobbs, finding the interesting programs and entering the source. I paid my dues on a Commodore 64 with a 5 ¼ disk drive then later a string of PC clones. Yea I know, cutting edge. Anyway, me and my hacker buddies pecked away at inputting many lines of BASIC & C code, saving and executing the files then watched a successful execution or a miserable fail, both of which required debugging time and effort to understand what the heck was wrong. Well after examining our customer issues with our code snippets, I began to have flashbacks and realized many of our customers are still performing the same pattern of “input, run, and pray”.
Some of our budding VersionOne developers are entering the sample C# or Java code found on our community site. When they finally get it to run, some feel the thrill of victory and others enter the “Perplexed Zone”. One of the more popular patterns is a customer starts to feel confident and make changes to the code samples to do something a little bit more interesting than listing a bunch of assets. They are then met with the challenge of figuring out how to isolate an attribute found on one of the pages in the VersionOne UI. For example, I had a customer ask “How do I print out the parent project of alpha project 1 (as illustrated here), how do I do this?” The next flurry of questions usually includes one or two of the following; “Do you have a list of what attributes are available?”, “Do you have a bunch of schemas of your database?”, and “How can I learn what parts and pieces of the API are at my disposal?
If I were forced to give a quick and dirty response, I would say it all boils down to the VersionOne metadata. Here is the content of my usual routine paraphrased and enumerated.
- Use the API – Before you even touch Visual Studio or Eclipse, get comfy with our API by using your browser. You can examine data, metadata and more all inside the browser.
- Perform a simple metadata query on the VersionOne asset that you are looking to work with. In this case scope (aka project). A meta query looks like this http://YourVersionOne/meta.v1/Scope?xsl=api.xsl
- Examine some of the attributes that are available to you. Be mindful of the interesting types like:
- Custom fields
- UI attributes not intuitively named in the metadata – There exists a small set of attribute names that do not match what you see in the UI. Just perform a data query for all instances of the asset type (ie. story), then search for the attribute name that you found in the VersionOne UI.
- Write a simple data query selecting different attributes of scope and don’t forget to try interesting types mentioned in above . Querying the data API looks like this http://YouVersionOne/rest-1.v1/Data/Scope
- Think about the app that you are going to write and try to write the query in the browser. After you nail down some of the minutiae of the query(s), you will get a flavor for your data and then start coding your app.
After asking our customers to do these simple things, I noticed that they had become self-sufficient rather quickly.
Oops, it looks like I’m over 500 words…