About

This library provides programmatic access to the Pivotal API using .net. Eventually, all the Pivotal APIs will be implemented, but for now it is the most commonly used items -- those methods involved in managing the stories and tasks.

NOTE: This started as an enhancement to a project on google code, but it ended up being an overhaul. However, there are still some remnants of that original code, so credit needs to be given to the author: http://code.google.com/p/pivotal-tracker-api/

To Do

• Write tests (and run them)
• Parts of the API for stories: Pagination, Deliver, Move, External Integrations, Attachments
• Review methods for consistency (make sure you can add a story as a static story method with a project object, as a method for a project, and a method in the story class to not require instances of any objects)

Common Terms

The term "fetch" is used whenever an operation is querying Pivotal. I wanted to make sure it is obvious when you are using data that you is associated with an object and when you are actively submitting a request to the API so you can control how much you hit the API.

The term "load" is used whenever an operation is using fetch to get data but then setting the value for a property (effectively using a cache of the returned results). I recommend using this Load + Property method over calling Fetch every time.

Serialization

Depending on your needs, you may need to modify the serialization method. It currently uses two steps:

1. Use list of ignored properties to remove nodes from what is submitted to Pivotal (for example, don't submit things like created_at, since that is generated by Pivotal)
2. Remove attributes that are null. The XmlSerializer will add an xsi:nil attribute to the nodes, so the serialization process removes elements that have this. The benefit is that you are only updating items that have values, but the downside is that it is difficult to clear values.

Usage

ApiToken / User Construction

For all operations, you need a user that has an ApiToken. You can retrieve the ApiToken using the PivotalUser class:

PivotalUser user = PivotalUser.GetUserFromCredentials(login, password);

or you can just construct the user if you know the token:

PivotalUser user = new PivotalUser(apiToken);

All operations require passing in a user so the token can be used to communicate with Pivotal.

Most CRUD operations have both a static and an instance operation so they can be invoked like this:

IList<PivotalProject> projects = PivotalProject.FetchProjects(user);

or this:

IList<PivotalProject> projects = user.FetchProjects();

Getting stories is similiar:

IList<PivotalStory> stories = Story.FetchStories(user, project.Id);

or:

IList<PivotalStory> stories = project.FetchStories(user);

Lazy loading is not used unless you specifically request it. For example, to get a project, you can use the method above, but the stories are not loaded. If you want to pre-load the stories, you would use the version of the method that has a flag to load the stories:

PivotalProject project = PivotalProject.FetchProject(user, projectId, true);
IList<PivotalStory> stories = project.Stories;

If you want to reload the stories for the project, then you need to call the Load method:

project.LoadStories();
IList<PivotalStory> stories = project.Stories;

OR

stories = project.LoadStories();

#License

This work is licensed under a Creative Commons Attribution 3.0 Unported License.

You are free:

• to Share -- to copy, distribute and transmit the work
• to Remix -- to adapt the work

Under the following conditions:

• Attribution -- You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).

With the understanding that:

• Waiver -- Any of the above conditions can be waived if you get permission from the copyright holder.
• Public Domain -- Where the work or any of its elements is in the public domain under applicable law, that status is in no way affected by the license.
• Other Rights -- In no way are any of the following rights affected by the license:
  • Your fair dealing or fair use rights, or other applicable copyright exceptions and limitations;
  • The author's moral rights;
  • Rights other persons may have either in the work itself or in how the work is used, such as publicity or privacy rights.
• Notice -- For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to this web page.