AxosoftAPI.NET Wrapper
Axosoft

AxosoftAPI.NET Wrapper

Axosoft’s API is a powerful tool that allows developers to build custom applications and extend the functionality of Axosoft Suite. Because of this, we decided to build a .NET API wrapper. This wrapper isolates developers from having to worry about spending too much time learning the details of a RESTful API or the nitty-gritty details of Axosoft’s API.

I know what you are thinking: this is all good, but how do I use it? Well, lets get straight to it.

To simplify things, we made the AxosoftAPI.NET library available as a NuGet package (available here). The first step is to add the AxosoftAPI.NET NuGet package to your Visual Studio solution. Depending on your preferences, you can install the package through the ‘Package Manager Console’ or the ‘Manage NuGet Packages’ window (how to install a NuGet package). In either case, the ‘AxosoftAPI.NET’ library reference will be added to your solution. You are now ready to start using the API wrapper.

Note: optionally you can download the source code and add it to your solution. Whatever you think is best for your project.

Now it is time to start typing some lines of code.

We begin with some ‘using’ statements (these are optional as you know, just keep in mind that these code examples will not use the classes’ fully-qualified names):

AxosoftAPI.NET using statements

Then we need to create an instance of the AxosoftAPI.Net proxy. Here is how:

create AxosoftAPI.NET proxy

Basically you need three values: a URL for the account being used; and a set of client id and client secret keys either from the account being used (see here) or in the case of 3rd-party applications one provided by Axosoft (see here).

Next, we need to authenticate against Axosoft. Our API uses OAuth2 protocol for authentication and authorization. In this example we show how you can easily authenticate using the Username/Password option:

Authenticate against Axosoft's API

Note: The AxosoftAPI.NET library also exposes a method for authenticating using the ‘Authorization Code’ option, but it is up to the developer to handle the necessary redirects required by the OAuth2 protocol (example application).

Before we start making calls to Axosoft’s API, it is important to point out a couple of things. The first point is that all calls made are dependent upon the permissions of the credentials used to authenticate. For example, if you have five projects in Axosoft, but the credentials used only have access to three projects, then when making a call to get all projects the API will return only those three projects. Makes sense, right?

The second point is that all the results returned by the library are wrapped on a class of type ‘Result’. This class contains three properties as shown below:

result_class

The ‘Data’ property contains the corresponding result return from the API; the ‘ErrorMessage’ contains the error returned by the API or ‘null’ if there was no error; and lastly, the ‘IsSuccessful’ flag is set to ‘true’ if no error, or ‘false’ otherwise. Pretty straight forward.

Ok, so let’s start making those calls I promised. The following example shows how to get all projects:

get_all_projects

Wow, that was easy.

Here is a piece of code from a console application which gets all the projects and then loops through them and writes to the console the projects Ids and names:

loop_thru_all_projects

In this case we used the property ‘Projects’ and its method ‘Get’ to retrieve the project. The AxosoftAPI.NET proxy has a property for every resource listed in our API documentation. Each of these properties is an interface for one or more methods. These methods map one-to-one with the different HTTP request allowed by each resource. For example, let us look at the ‘Contacts’ resource. From our documentation we can see that it allows for six different calls:

Axosoft API Contacts

If we now look at the ‘Contacts’ property in the proxy object, we can see that it contains a method call for each one of these HTTP requests:

AxosoftAPI.NET Contacts methods

Note: the ‘Update’ method corresponds to the POST-update HTTP request; and the ‘Create’ method corresponds to the POST-create/add HTTP request.

Keep in mind some of these methods have overload methods as well. For example, the ‘Get’ method has a one-optional-parameter method which will return all objects; it also has an ‘integer’ – resource Id – parameter method which will return one single object based on the Id value.

Here are a couple of examples from the same console application for creating a new project and adding a new feature to it:

Create a new project

Described in a few words, you need to create a ‘Project’ object, populate the Name property – all other properties are optional – and pass it as the single parameter to the ‘Create’ method of the proxy’s ‘Projects’ property.

Create a new feature

Then, for the new feature, you need to create a new ‘Item’ object, populate the corresponding properties (see our API documentation for more details about required fields and other notes), and then call the ‘Create’ method of the proxy’s Feature property.

For more examples just download the example application and play with it. If you have questions, please feel free to contact us at support@axosoft.com. We are happy to help you.

Stay on the cutting edge of software development by getting innovative tips, trends and stories delivered to your inbox every month!

Agile project management software
Plan, develop, review, and ship fast

Visit Axosoft.com

The downright luxurious Git client
For Windows, Mac & Linux

Visit GitKraken.com