Skip to content

Latest commit

 

History

History
122 lines (101 loc) · 6.43 KB

README.md

File metadata and controls

122 lines (101 loc) · 6.43 KB
Raw

SchooxSharp

###Documentation We've tried to include as much of the documentation from the API's web site as possible. Please use the support site for the most up to date information about the API. https://www.schoox.com/api/docs

###Getting Started ####Configuration There are two ways to configure the services, the recommended method is to add the API Key and Academy ID to your applications AppSettings configuration area; optionally, you can add the Base URL as well (although, you likely won't need to do this unless we introduce a staging API).

<configuration>
  <appSettings>
    <add key="SchooxSharp.AcademyId" value="[your academy id integer]"/>
    <add key="SchooxSharp.ApiKey" value="[your api key]"/>
    <add key="SchooxSharp.BaseUrl" value="https://www.schoox.com/api/v1"/> <!--Optional-->
  </appSettings>
</configuration>

If your application has no configuration file, or you're sourcing this information from a database you may alternatively set these variables during the SchooxService initialization. See the section below regarding the SchooxService.

####ISchooxService and SchooxService The SchooxService implements ISchooxService in the event you need to extend or expand on the very basic one provided. SchooxService is used by every SchooxApiBase client class, it manages generating the proper RestRequest and keeping track of the ISchooxService either passed to the Client class or generated by the Client class.

You will also need to reference the namespace below:

using SchooxSharp.Api.Services;

There are two ways to initialize a SchooxService, if you choose to enable without any parameters, it will load the API Key and Academy ID from your application configuration file.

var mySchooxService = new SchooxService();  //pulls configuration from application config

The other way is to pass in the API key and Academy ID manually.

var apiKey = "myApiKey";
var academyId = 123;
var mySchooxService = new SchooxService(apiKey, academyId);

####API Clients You will need to reference the namespace below to access the clients:

using SchooxSharp.Api.Clients; //client classes
using SchooxSharp.Api.Models;  //data models

There are 5 API clients you can access, they you can find all of their sources and detailed information here (https://www.schoox.com/api/docs). To access them via the code, simply create a new instance; each API class allows you to provide a ISchooxService, or if none is provided it will create its own instace of a SchooxService.

var coursesClient = new Courses(mySchooxService);
var curriculumsClient = new Curriculums(mySchooxService);
var dashboardClient = new Dashboard(mySchooxService);
var examsClient = new Exams(mySchooxService);
var usersClient = new Users(mySchooxService);

####A Quick Example All Together Here's a quick example found inside the Sample project. Just being used a console application.

//note the App.config file that has the values for auto loading the configuration
var schooxService = new SchooxService();

var dashboard = new Dashboard(schooxService);
var courses = new Courses(schooxService);

//lets get the courses
var coursesResponse = dashboard.GetCourses(Roles.SchooxInternalEmployee);

if (coursesResponse.RequestSuccessful && coursesResponse.Data != null)
{
    Console.WriteLine("Request from\n{0}\n{1} courses returned:", coursesResponse.Response.ResponseUri,
        coursesResponse.Data.Count);
    
    foreach (var course in coursesResponse.Data)
    {
        Console.WriteLine("#{0} - {1} - # of Students: {2}", course.Id, course.Title, course.Students);
    }

    //now that we have the courses, let's pull details for the first one
    var firstCourse = coursesResponse.Data.FirstOrDefault();

    if (firstCourse != null)
    {
        var courseDetail = courses.GetDetailsForCourse(firstCourse.Id);
        Console.WriteLine("\nDetails for Course:\n{0}", courseDetail.Data);
    }
}
else
{
    Console.WriteLine("No courses found or data null for \"{0}\" courses, check the URL\n{1}.", Roles.SchooxInternalEmployee,
        coursesResponse.Response.ResponseUri);
}

You will notice for an ease of use (and primarily for testing), all of the model classes come with a .ToString() override to attempt to display all of the properties. Luckily, this makes it easy to dump the results to a log. :)

###Dependencies

  • Newtonsoft.Json >=7.0.1
  • RestSharp >=105.2.3

###Compatibility This code should work with .NET 4.5.1 and above, and with Xamarin frameworks for iOS, Mac, and Android.

###Sample Code You can find a sample project in src/SchooxSharp.Sample. It will guide you through making some basic requests.

###Testing There is a unit test project; at the moment, all of the create/edit/delete tests are being ignored. As such, they have not been tested against the API server. We're waiting on a proper staging environment that we can execute these tests against.

###Model Variance The Schoox API has some small quirks in the models.

For example, we reuse many models, despite the entire model not being populated. Additionally, many models for New and Update are different than their counterparts. You must check the documentation to know what to expect out of what will be populated in these models. For ints and bools inside a model, they for the most part are all listed as nullable properties, this allows you to say myInt.HasValue and myInt.Value to determine whether or not the value is present.

Another example lives in the Course model, in particular the "Scope" property is an object. In cases where there is just one element in scope, it will return a string. In cases where there are more than one element, it will return an array of strings. This makes it very difficult to parse reliably.

Another example lives in the Curriculum model, in some requests object Courses is an integer, and in others it's a List object.

###Bugs Please submit any bugs to the bug section of this API and we'll look to address them as soon as we can.

###Parameters and Nullables/Optionals/Defaults Functions with "optional" parameters are exactly that, you don't have to fill them in if you don't want to. Some parameters are given the defaults that They exist to let you know what you must provide, and what's optional.