.NET Framework Client¶

The .NET Framework client supports calling the API from C#, Visual Basic or any other Common Language Runtime language.

Getting started¶

The client should be installed via NuGet

> Install-Package EcEnglish.Api.Client

Once installed you can get an ApiClient object as follows:

using System;
using EcEnglish.Api.Client;

namespace Sample
{
    public class ApiClient ApiClientFactory
    {
        public static ApiClient CreateClient()
        {
            ApiClientConfig config = new ApiClientConfig();
            config.ApiUrl = new Uri("https://api.ecenglish.com");
            config.ApiKey = "my-api-key";

            ApiClient client = new ApiClient(config);
            return client;
        }
    }
}

Api Overview¶

The .NET library models the API as a Message Based Webservice. To invoke a particular function you simply need to construct an instance of the desired message and pass it to the ApiClient.Send method. Details of messages available can be found throughout the rest of this documentation.

ApiClient client = ApiClientFactory.CreateClient();
TestConnectionRequest request = new TestConnectionRequest();
TestConnectionResponse response = client.Send(request);
Console.WriteLine(response.Message);

You can also use the SendAsync version of this method to perform the operation asynchronously

ApiClient client = ApiClientFactory.CreateClient();
TestConnectionRequest request = new TestConnectionRequest();
TestConnectionResponse response = await client.SendAsync(request);
Console.WriteLine(response.Message);

The Send and SendAsync methods use generics to infer the return type of the API method at compile time:

public interface IApiClient
{
    T Send<T>(IReturn<T> message);
    void Send(IReturnVoid message);
    Task<T> SendAsync<T>(IReturn<T> message);
    Task SendAsync(IReturnVoid message);
}

public class TestConnectionRequest  : IReturn<TestConnectionResponse>
{
}

public class TestConnectionResponse
{
    public string Message { get;set; }
}

Links¶

Some API resoponses contain links to other related resources. You can use the Fetch extension method to fetch the linked resource in a typesafe way. For example to fetch the product offerings for a school you can do this:

// get the schools
ApiClient client = ApiClientFactory.CreateClient();
GetSchoolsRequest request = new GetSchoolsReqyest();
GetSchoolsResponse response = client.Send(request);
SchoolWithOfferingsLink firstSchool = response.Results[0];

// Get the linked resource
GetProductOfferingsResponse productOfferings = firstSchool.ProductOfferingsUrl.Fetch(client);

Paging¶

The number of results returned from many messages is limited to 200 records. If a web service response would have contained more than 200 records then it will include a field named NextPage with a link to the next page. You can use the PageResults extension method to automatically fetch all the pages as needed:

// print the school and product codes of all the product offerings
ApiClient client = ApiClientFactory.CreateClient();
GetProductOfferingsRequest request = new GetProductOfferingsRequest();
GetProductOfferingsResponse response = client.Send(request);

foreach (ProductOffering offering in response.PageResults(client))
{
    Console.WriteLine("School = {0}, Product = {1}", result.School.Code, result.Product.Code);
}

Alternatively you can follow the NextPage links in a loop to fetch the individual pages

// print the school and product codes of all the product offerings
ApiClient client = ApiClientFactory.CreateClient();
GetProductOfferingsRequest request = new GetProductOfferingsRequest();

GetProductOfferingsResponse page = client.Send(request);
while (page != null)
{
    foreach (var result in page.Results)
        Console.WriteLine("School = {0}, Product = {1}", result.School.Code, result.Product.Code);

    if (page.NextPage.IsEmpty)
        page = null;
    else
        page = page.NextPage.Fetch(client);
}

Error handling¶

The library will throw an EcEnglishApiException to indicate any errors.