RSA.Archer.Api.Client 0.3.1-alpha

Note : Please use Visual Studio 2017 to develop projects that use this package. Visual Studio 2015 has known issues with .NET Standard 2.0.

The RSA Archer API Client is a library for making calls to the RSA Archer API. Currently, the REST API is supported. The SOAP API is planned to be supported in the future.

The library makes it easier to get up and running with the RSA Archer API by handling the mechanics of making calls and reading responses. All methods in the library are asynchronous and awaitable.

Getting Started

To talk to the REST API, use the class ArcherRestClient. The host parameter should include the full path to the REST API. (e.g. https://archer.company.com/RSAarcher/api)

ArcherRestClient client = new ArcherRestClient(HOST);

On its own, the ArcherRestClient simply supports making REST calls. The consumer must provide an ArcherRequest object along with the class type to which the response will be deserialized from JSON.

POST Example

LoginRequest loginRequest = new LoginRequest { InstanceName = "Archer", Username = "user123", Password = "password123" };
ArcherRequest<LoginRequest> request = new ArcherRequest<LoginRequest>("/core/content", loginRequest);
LoginResponse response = await client.PostAsync<LoginRequest, LoginResponse>(request);
SessionContext session = response.SessionContext;

GET Example

ArcherRequest contentRequest = new ArcherRequest("/core/content");
contentRequest.SessionContext = session; //Need session from a login request, such as above example.
ContentResponse contentResponse = await client.GetAsync<ContentResponse>(contentRequest);

Extensions

The client alone is very helpful, but the real power of the library is in the extension methods available for many API calls. In the above login example, instead of needing to write the request and response classes and form a request and POST it, it would be much simpler to just make a method call.

var session = await client.LoginAsync("user123", "password123", "Archer");

The ArcherRestClient does not have a LoginAsync method. It only provides the basic REST calls. However, through extension methods, additional calls can be added to the ArcherRestClient to make consuming applications much simpler.

Namespaces

Extension methods are added by pulling in the corresponding namespace. To get the LoginAsync extension, simply add the namespace RSA.Archer.Api.Client.Authentication.

using RSA.Archer.Api.Client.Authentication;

Many more such extensions are available for things such as users, groups, content, metadata, and datafeeds. Explore the namespaces available under RSA.Archer.Api.Client to see what is possible.

Content Example

To get a session and read content, combine the power of multiple namespaces.

using RSA.Archer.Api.Client.Authentication;
using RSA.Archer.Api.Client.Content;

SessionContext session = await client.LoginAsync("user123", "password123", "Archer");
ContentRecord content = await client.GetContentAsync(12345, session);

If an extension method is not available for a certain REST API call, the logic in the first examples can still be used to make the call.

Errors and Validation

Validation Messages

The REST API validates calls and returns validation messages. These messages can be translated to .NET exceptions using the EnsureSuccessful extension method of the ArcherResponse class. This is what the various extension methods do to validate the responses.

A single validation message will be translated to an HttpRequestException and thrown.

If there are multiple validation messages, they will each be translated to an HttpRequestException then all thrown inside a single AggregateException.

HTTP Errors

Additionally, it is possible that the HTTP request itself could fail with an HTTP status code. The ArcherRestClient will call the HttpResponseMessage.EnsureSuccessStatusCode method for each HTTP call, which will throw an HttpRequestException if the HTTP status code is not successful.