TIES API v1 Documentation
This document provides details for accessing the TIES API. You will need your Ties issued API Key and Secret Key in order to authenticate against the RESTful Ties API. NOTE: you should never share your secret key with anyone outside your organization.
Authentication
Using .NET

Endpoints
Authentication
All requests to the TIES API follow the same authentication rule. The TIES API uses a keyed HMAC (Hash Message Authentication Code) to authenticate its callees. In order to sucessfully authenticate against the API, you must concatenate certain elements of your request together to form a string, and then use your secret key to calculate the HMAC of that string. This is called signing the request. The output of this HMAC calculation is called the signature. Once you have produced the HMAC signature, you will add it to your HTTP request using the syntax explained below.

An Example REST Request

GET /Students/1 HTTP/1.1
Host: ties.k12.mn.org
ties-date: Wed, 17 Nov 2010 17:03:44 GMT

Authorization: TIES 0PN5J17HBGZHT7JJ3X82:1XHiZOwMVPpvdijjn1AGS7EAInY=

The TIES Authentication Header

The standard HTTP Authorization header is used to pass the authentication request to the TIES API. The form of this request is:
Authorization: TIES APIKey:Signature

The Signature element is the RFC 2104HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, then the requester will have demonstrated possession to the TIES API Secret Key. The request will then be processed under the identity, and with the authority, of the entity to whom the key was issued

You should never send your secret key with your request, but only use it as a means of encrypting the StringToSign

The below is an example of how to construct the Authorization header

Authorization = "TIES" + " " + APIKey + ":" + Signature;

Signature = Base64( HMAC-SHA1( UTF-8-Encoding-Of( YourSecretAccessKey, StringToSign ) ) );

StringToSign = HTTP-Verb + "\n" +
Date + "\n" +
FullRequestUrlWithPathAndQueryString;

FullRequestUrlWithPathAndQueryString = "https://api.tiescloud.net/v1.0/Schools/1?filter=true&schoolyear=2010"

HMAC-SHA1 is an algorithm defined by RFC 2104 (go to RFC 2104 - Keyed-Hashing for Message Authentication). The algorithm takes as input two byte-strings: a key and a message. For Ties API Request authentication, use your Ties Secret Key as the key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest.

Mandatory Time Stamp Requirement

A valid time stamp using the ties-date header is mandatory for authenticated requests. Furthermore, the client time-stamp included with an authenticated request must be within 15 minutes of the TIES API System time when the request is received. The intention of these restrictions is to limit the possibility that intercepted requests could be replayed by an adversary.

The format of the time must always be in UTC (otherwise known as Greenwich Mean Time or Universal Time) in the RFC1123 format.

How to construct this in .NET?

Encoding ae = new System.Text.UTF8Encoding();
HMACSHA1 signature = new System.Security.Cryptography.HMACSHA1(ae.GetBytes(YourSecretKey.ToCharArray()));
string method = "GET"; string request = "https://api.tiescloud.net/v1.0/Schools/1?filter=true&schoolyear=2010";
string utcDate = String.Format("{0:r}", DateTime.Now.ToUniversalTime());
string StringToSign = String.Format("{0}\n{1}\n{2}", method, utcDate, request);
string _calculatedHash = Convert.ToBase64String(signature.ComputeHash(ae.GetBytes(sts.ToCharArray())));
Optional Parameters
Below are all the optional querystring parameters for use with the API endpoint. NOTE - pay attention to the individual endpoint pages to know which of these optional parameters can be used with the different endpoints

Enrollment Date

&EnrollmentDate=yyyyMMdd (20101129) (int)

School Year

&SchoolYear=yyyy (int)

School Id

&SchoolId=XXX (string)

Counselor Id

&CounselorId=XXX (int)

Teacher Id

&TeacherId=XXX (int)

House Id

&HouseId=XXX (string)

Group Id

&GroupId=XXX (decimal)

StudentIds

&StudentIds=XXX,XXX,XXX (comma-separated list of student ids)

Student Name

&studentname=XXX (string, performs wildcard search)

Grade

&grade=XX (string; 01-12)

Ethnicity Id

ðnicityid=XX (int)

Gender

&gender=X (string, M or F)

Gifted & Talented

&giftedandtalented=true|false

Special Ed

&specialed=true|false

Title 1

&title1=true|false

Language English Proficiency

&ell=true|false

FamilyId

&familyid=XXXX (decimal)

PrimaryFamily

&primaryfamily=true|false
Optional Sorting Parameters
When retrieving more than one result, you can use these parameters to manage what you receive back.

Results Per Page

&rpp=XXX (int, number of results per page)

Order By

&orderby=XXX (string, column to sort the results by)

Sort Direction

&orderby=asc|desc (asc or desc sorting)