student-api-graphql

A GraphQL Wrapper for Ellucian's Banner Student REST API

This project's purpose is to aggregate all of the StudentAPI endpoints into a single GraphQL endpoint with intuitive types that are connected via the proper relationships. Using GraphQL to expose the StudentAPI endpoints offers many benefits, however considering it is just a wrapper, many of the limitations of the REST implementation remain.

Disclaimer

This project is a work in progress! This is also just a user-contributed project. I am not affiliated with Ellucian.

Install

git clone https://github.com/aeiz/student-api-graphql.git
cd student-api-graphql
npm install

Configuration

Edit config.js with your own settings.

Config Option	Description	Default
API_BASE_URL	Point to your school's StudentAPI endpoint	https://api.university.edu/StudentApi/api
SERVER_PROTOCOL	GraphQL Server Protocol (http or https)	http
SERVER_ADDRESS	GraphQL Server Address	localhost
SERVER_PORT	GraphQL Server Port Number	3000
CRYPTO_ALGO	Crypto Algorithm	aes-256-ctr
JWT_SECRET	JSON Web Token Secret	shhhhh!
JWT_EXPIRE	JSON Web Token Expiration Duration (in minutes)	60

Running the GraphQL Server

npm start

Alternatively, if you use want to use forever, there is a wrapper (server.js) to support running babel-node via forever:

forever start server.js

Once the server is started, browse to http://localhost:3000/graphql to use GraphiQL (A graphical interactive in-browser GraphQL IDE).

Authentication

This project relies on the authentication mechanism implemented in the StudentAPI (basic HTTP authentication) application. However, I've exposed a mutation (createAuthenticationToken) that enables authentication through JWTs (JSON Web Tokens). Either can be used.

If you want to use JWTs, here's an example of the GraphQL mutation you would use to retrieve the token:

mutation {
  createAuthenticationToken(username: "username", password:"password") {
    token
    expires
  }
}

Schema

The schema is generated programmatically, but you can view the schema language description by browsing to http://localhost:3000/schema when the server is running. The schema language description is also saved in schema.graphql.

A graph diagram of the schema definition generated by graphqlviz is available here.

You can also view the schema interactively using the GraphQL Voyager tool here.

Documentation of the schema generated via graphql-docs is available here.

Here's an example query:

query {
  personIdentification(bannerId: "bannerId") {
    person {
      names {
        fullName
        firstName
        middleName
        lastName
      }
      dateOfBirth
    }
  }
}

Debug

This project uses debug, which can be enabled by setting the DEBUG environment variable.

Windows:

set DEBUG=*,-babel,-express*

Linux/Mac:

DEBUG=*,-babel,-express*