This documentation walks through how to connect a client system to the School Info API. You should be familiar with RESTful API concepts.

Credentials & Access

If you haven't done so already, now is the time to get your credentials from ContactUs@ScholarSnapp.org. Even if you're already a Scholar Snapp API client, you will need credentials specifically provided for this system.

The system uses JSON Web Token (JWT) authentication. If you're reading this, you're probably familiar with JWT, but, if not, it's RFC 7519, with a pretty good overview here and a Wikipedia entry chock full of references to further information here.

You'll be issued a Client ID and a Client Secret.

Connection Quick Start

Connecting to the API is straightforward. If you've used RESTful APIs and JWTs, the steps will look familiar. The steps are:

Detail on each step follows.

Step 1. Use your Credentials to Obtain a Token

Many code libraries provide a method to access a JWT token. We'll go through the steps so you can see what's going on. The initial call to request a token is a POST of your credentials to the /api/authApp endpoint:

POST       {{ base url }}/api/authApp
Header:    Content-Type: application/json

{
     "clientid": "your-clientid-here",
     "secret": "Y0ur_ap1_s3cr3t_h3r3"
}

Presuming your credentials are valid, you'll receive back a JWT:

{
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRJZCI6InlvdXItY2xpZW50LWlkLWhlcmUiLCJjbGllbnROYW1lIjoiWTB1cl9hcDFfczNjcjN0X2gzcjMiLCJpYXQiOjE1NjAxMDUzMjUsImV4cCI6MTU2MDE5MTcyNX0.p9VCJcxSqsTSugNe3ewlDGDPrKTNOAF3QgYlMi4jq-8"
}

Usage notes:

• You'll use the token value in subsequent calls, sending the value inside an authToken header.
• As with many JWT implementations, the token contains the expiration value in an "exp" field. The documentation and debugger at jwt.io are helpful if you're new to JWT. Use the token example above to see what's contained in the School Info API JWT.

Step 2. Call the API Using your Token

Once you have a valid JWT, you can call the API. Calling the API is a simple GET request, with optional parameters to search and page through results. You'll include the JWT in a header sent with your request.

GET       {{ base url }}/api/schools
Header:    authToken "eyJhbGciOi ... more here ... YlMi4jq-8" 

Usage notes:

• Simple, right?
• A call to /api/schools with no parameters returns the first 20 records in the system, sorted alphabetically.
• You can modify the records returned by adding search parameters and values as a querystring (e.g., schools?city=Austin&state=TX). 
• You can sort the results (e.g., order=city), return more or fewer records (e.g., limit=100), and page through results (e.g., page=2).

Step 3. Review the Results

A call will return an array of records. An abbreviated example is shown below.

In addition to the school data, note the "meta" fields, which show the starting page, the total count of records returned, and the current page of records:

{
    "meta": {
        "start": 0,
        "total": 32,
        "totalPages": 2
    },
    "schools": [
        {
            "snappId": "9ce3a90f-63a7-4739-b5e5-af6e9b740156",
            "ncesId": "480894000001",
            "ceebCode": "000000",
            "name": "01 AAA TESTING Academy",
            "aka": "TEST 01",
            "address": {
                "addressLine1": "1234 Maple St.",
                "addressLine2": "1234 Maple St.",
                "city": "Austin",
                "state": "TX",
                "zip": "78701"
            },
            "mailingAddress": {
                "addressLine1": "1333 Maple Street",
                "addressLine2": "",
                "city": "Austin",
                "state": "",
                "zip": "78701"
            },
            "phone": "(512) 555-0001",
            "charter": null,
            "snappSchoolType": "High School",
            "ncesDistrictId": "4808940",
            "stateSchoolId": "",
            "stateDistrictId": "",
            "latitude": "30.267200",
            "longitude": "97.743100",
            "districtName": "Austin Independent School District",
            "website": "www.example.edu/home/"
        },
        
        ... more records here ...

        {
            "snappId": "e999b30b-25c9-4053-8088-63407476e043",
            "ncesId": "BB081102",
            "ceebCode": "",
            "name": "Apple Beta Learning Center",
            "aka": "",
            "address": {
                "addressLine1": "411 Waverly Oaks Rd",
                "addressLine2": "",
                "city": "Waltham",
                "state": "MA",
                "zip": "2452"
            },
            "mailingAddress": {
                "addressLine1": "",
                "addressLine2": "",
                "city": "",
                "state": "",
                "zip": ""
            },
            "phone": "(617) 484-4470",
            "charter": false,
            "snappSchoolType": "High School",
            "ncesDistrictId": "",
            "stateSchoolId": "",
            "stateDistrictId": "",
            "latitude": "42.387184",
            "longitude": "-71.203255",
            "districtName": "",
            "website": "www.example.edu/schoolId=987"
        }
    ]
}

Next Steps

After you verify that you can connect to the system, a great next step is to review the full API documentation. The API Documentation page covers more about usage, and the full technical details are published on SwaggerHub here. You can learn about all the supported search parameters, and find out more about the definitions behind individual fields.