The Scholar Snapp solution was updated for the 2018-2019 application cycle. The full set of changes proposed for the API are fairly ambitious, so we've made essential changes first (e.g., updating to the latest version of the Snapp Profile), and will be making further changes throughout the application. All changes for v4.0 will be non-breaking for existing implementers. Taking advantage of new features will require additional development, of course. This section provides an overview of current and forward-looking changes.

The Snapp team heartily thanks all the implementers, technologists, and subject matter experts that provided input.

We welcome and accept feedback any time. If you are a current or prospective implementer of the Scholar Snapp Profile Data Standard or the Snapp Central API and would like to provide input or be included in the next RFC period, please send a note to Governance@scholarsnapp.org with your contact information.

This documentation is a companion piece to What's New in the Snapp Profile v4.0, which describes the changes to the Snapp Profile data model.

Overview

The information that follows describes changes in the latest version of Scholar Snapp. 

The changes include:

Detail on each change follows.

Changes in the Snapp API v4.0

Support for Snapp Profile v4.0 with Backward Compatibility

The Scholar Snapp Profile Data Standard XML payload is updated for the 2018-2019 scholarship cycle. The Snapp Central API is updated to serve XML that conforms with the new standard, but maintains backward compatibility with the Snapp Data Standard v2.0 (from the 2016-2017 cycle) and v3.0 (from the 2017-2018 cycle).

Change Detail

Pulling a new Snapp Data Standard is enabled via an HTTP GET with a querystring key version and the value 4. 

Retrieving a v4.0 Snapp Profile from Snapp Central:

HTTP Method: GET
Request URL: https://auth.scholarsnapp.org/api/profile/snappfile?version=4
Header:
  Authorization Bearer [bearer token value]

Sending a v4.0 Snapp Profile to Snapp Central:

HTTP Method: POST
Request URL: https://auth.scholarsnapp.org/api/profile/snappfile?version=4
Headers: 
  Authorization Bearer [bearer token value]
    Content-Type application/xml

Current implementers will note that calls to the API are the same as the current version other than the version value.

Backward Compatibility

In order to support backward compatibility and a seamless upgrade path for current implementers:

• Sending version=3 will continue to emit and accept profiles conformant with Snapp Data Standard v3.0.
• Sending version=2 (or omitting the version key from the querystring) will continue to emit and accept profiles conformant with Snapp Data Standard v2.0.

Changes In Progress or Coming Soon

This section describes changes to the Snapp solution that are expected sometime in the 2018-2019 scholarship application cycle.

Create Optional Streamlined Registration Path (SSDS-62)

Most users first visit Snapp by reference from another site. On the first visit, users are (of course) required to register and set up an account.

However, this means that registration is usually an interruption to a program flow or user experience in another context. So, we (and end-user applicants) want that interruption to be as low-effort and fast as possible. For that reason, we ask the minimum possible information on registration (e-mail, password).

Some partners have encouraged us to ask for a little more information on our registration (primarily, e.g., First Name & Last Name). The idea is that any given account will have at least a thin core of data beyond just an e-mail address. This creates an obvious tension between adding more information and keeping the process streamlined.

Change Detail

One approach is to offer a streamlined registration path, whereby a partner can securely send (e.g., via HTTP POST) information to Snapp that can pre-populate the registration form with basic, non-invasive core data our partner "knows" about an applicant that Snapp does not.

For example, most partner application flows offer Snapp after the partner application already knows the applicant's e-mail address, first name, and last name. If that information was securely sent to Snapp, it would smooth even the existing registration process while ensuring that the applicant has a useful core of data at registration time.

Requirements include:

• The streamlined registration is optional. In the near-term, this will ensure that existing implementations are unaffected. However, we believe it will always be optional both to keep the bar for implementation to a minimum, and because many partners will have policies that prevent data exchange of any kind — even well-intentioned data exchange — without explicit user consent, and may not want the UI/UX overhead to get what they feel is informed consent.
• We will offer a small range of core data around e-mail, name, and basic contact info – and not anything that an applicant might find alarming (e.g., demographic information, financial information). 

Improve "No Profile Found" Response

There is a not-uncommon program flow in which a user is sent to Snapp from a partner site to retrieve their application information, but the user doesn't already have a profile. The program flow allows the user to set up an account, but when the API returns to the referring site, it sends a message in the body of the response noting that a profile wasn't found instead of the XML payload expected when a user already has a Snapp account.

Implementers have noted this adds complexity to their client code since they might receive either an XML payload or a literal text string as a response.

Change Detail

We will now send an XML file conformant to the Snapp Data Standard, even for newly registered users.

The minimum valid Snapp profile contains three pieces of user-collected data: e-mail address, first name, and last name. The Snapp registration currently requests only an e-mail address from new users.

Implementers have suggested adding first name and last name to the initial Snapp registration, or simply sending placeholder values. We are adding placeholder values, simply to keep the initial setup as fast as possible, as the new user flow is already an interruption to the flow of our partners' systems.

Provide fully RESTful API with a JSON Representation of the Snapp Profile

The primary data payload for Scholar Snapp is XML, betraying its roots as a downloadable file developed in the 2000s. While the file is wrapped in a modern, somewhat RESTful JSON API, implementers have suggested that the option to interact with a fully RESTful API with a JSON representation of the Snapp Profile file would be desirable.

Change Detail

We are now adding RESTful endpoints and JSON support to the existing API, but will continue to support the current XML-based payload via the existing endpoints. The OAuth flow will remain the same across the endpoints, and the JSON representation will be harmonized with the XML representation of an applicant's Snapp Profile.

We are implementing the following for differentiating the content type:

• Snapp Central will honor a new Accept header for the GET method:
  • A GET with an Accept application/xml will return XML
  • A GET with an Accept application/json will return JSON
  • For convenience, a new querystring type parameter will be supported for GETs (e.g., type=json, and type=xml); if both the Accept header and the type parameter are provided, the type parameter will be honored
  • For backward-compatibility, a GET with nothing specified will return XML
• Snapp Central already has a Content-Type header for the POST method:
  • A POST with Content-Type application/xml will continue to expect XML
  • A POST with Content-Type application/json will expect JSON

Auto-Enter Information from MyStudentData Files

Many Scholarship Applications request data from an applicant's FAFSA. Accordingly, the Snapp v3.0 XSD conveys several frequently used FAFSA fields, like Expected Family Contribution, Adjusted Gross Income, and so forth. The U.S. DoE has an initiative that allows students to create a downloadable data file containing FAFSA data.

See this link, for example, about the program:
https://studentaid.ed.gov/sa/resources/mystudentdata-download

See this link, for example, about the data format:
https://ifap.ed.gov/eannouncements/attachments/FAFSAMyStudentDataDownloadRecordLayout.pdf

The MyStudentData file is one of the file types in the Snapp enumeration. Users and implementers have noted that if the Snapp Central API supports the upload of a machine-readable format, it would make sense to read the file and complete any relevant Snapp elements not already present.

Change Detail

We now support the automated entry of data from the MyStudentData download file.

The 2017-2018 MyStudentData CSV file contains the following fields that map to elements in Snapp, or provide information that would enable us to add data to an applicant's Snapp Profile:

To be clear, we haven't seen very many of the CSV files in use by applicants. However, we have worked with individuals to download the file, and it's reasonably easy and quick (if one knows where to look). We will therefore invest in some communication and documentation to let students know about this potentially useful time-saving approach to adding data to their profile.

For the initial version, we will add information only if it's not already present (vs. update or synch information). However, we will also accept information any time so an applicant can realize the benefit at any point in the applicant lifecycle.

Support an Optional, Persistent, Revocable Profile Access Token

The current token (i.e., the OAuth bearer token) that client systems use to access a Snapp Profile is short-lived, effectively meaning that end-user applicants must supply Snapp with login credentials every time they grant access to a client system to read or write their data. This provides a security benefit to applicants. It also ensures that Snapp users are aware that their data has been accessed.

However, this level of control comes at a cost to convenience, which some users view as a disincentive to using Snapp. It also imposes some limitations on client systems: for example, the short-lived nature of the token effectively removes a store-and-forward queue on the client side, and makes transient errors difficult to recover from.

Allowing an optional, persistent token provides secure support for:

• More frequent exchange between client systems and Snapp. Some clients have understandably chosen to limit the exchanges with Snapp because of the detriment to their users' current experience. This change would improve the experience such that more frequent exchanges are not clunky. But client systems could also, for example, poll for and pull new information from Snapp at the start of a user's session and push new information to Snapp at the end of a user's session. This would be possible today, but a frustrating experience.
• Asynchronous exchange. Client systems could initiate a data exchange without interfering with their end-user's experience. Client systems today do not have the option for background synchronization, queuing, or recovery from a longish but transient error.

This change supports an opt-in, longer-lived, revokable access token, allowing end-users to grant ongoing permissions for a particular client system to update their Snapp Profile data.

Change Detail

Applicants may now choose their own balance between security and convenience, and retain control over the permissions they grant to client applications. The features generally follow those principles:

• The persistent token is opt-in for the applicant, meaning that users can continue to require credentials every time their profile data is accessed. Client systems will be passed a timeout value which will indicate the lifespan of a token.
• The persistent token is opt-in for client systems as well. In other words, client systems can continue to work as they do today. Initially, this is a necessary convenience so as not to impact current implementations – but, at this point, we envision continuing to support this option. The change does imply some user experience, user interface, and core development work on the client side, so we want to let client system owners choose if and when to do that work.
• The persistent token will be revokable through the Snapp user interface. We will encourage client systems to offer a way to purge persistent tokens as well.
• We will continue to track access to Snapp Profile data, and expect to provide a means for applicants to view a history of access to their profile.

Because this change has security/privacy implications for our users, we are moving deliberately (read: slowly). In addition, so that this change is transparent for client systems, we will ensure our existing integrations are aware of the change, and have a chance to provide input.