Since June 2012, Clever has only had one version of our API: v1.1. We’re now ready to introduce v1.2! In this post, we’ll talk about what the new version means for our customers.

Why API versioning?

Very few, if any, non-Clever developers saw API v1.0. Early beta versions had this designation, but as we finalized our API design we released v1.1, and it’s been our only version ever since. Our API change policy has allowed us to add and deprecate features with notice given in our application newsletters, as well as the flexibility to release bug fixes as needed.

In practice, we’ve learned that any change, no matter how small, can be a breaking change to an integration—adding new fields, new values on fields, or even improving district-facing sharing tools can lead to unhandled exceptions that impact an application’s ability to sync with Clever. What we think are minor bug fixes can end up being very confusing to apps.

As a result, our internal teams have been hesitant to make any changes to our API—how much positive and negative impact will this change have on our customers?

We decided to version our API in order to provide a stable experience for all of our customers while retaining the freedom to iterate on our product. It will also deliver new features that make the experience better for all of our applications but allow them to access them on their timetable.

To review our policy on API versioning moving forward, see the API Change Policy in our developer documentation

Introducing API v1.2!

As v1.2 is our first new API version ever, we’ve made it as easy to upgrade as possible – we’re adding some exciting new features, but the core of our API will not change, so upgrading to the new version will require very little development time. Check out the schema here.

New features

Schools array

Clever’s data model associates students and teachers with a single primary school but allows them to be associated with other schools’ sections.

In v1.1: In order to get the full list of schools a user is associated with, an application needs to iterate through all of their sections and check each section’s school association.

In v1.2: In addition to the school field on the student and teacher objects, which represents the user’s primary school, we are adding a ‘schools’ field, which will contain a list of all schools the user is associated with. The schools array will be filtered so only schools shared with you will appear. Here’s an example:

‘schools’: ["4fe3ff50dfa547000000033c", "4fe3ff50dfa547000000035d", "4fe3ff50dfa547000000023a"]

The array will be visible on:

• /v1.2/students and all related endpoints
• /v1.2/teachers and all related endpoints
• /v1.2/events/ and all related endpoints
• /v1.2/me

Pause start and end dates

During school year rollover, districts may choose to pause their data in Clever, which means we will no longer sync new data for that district until the pause end date, which usually represents data being ready for the new school year.

In v1.1: This data is only accessible in the Clever Dashboard.

In v1.2: We added pause_start and pause_end as fields on our status endpoint. The value will be in Date format, e.g. 2017-02-03T14:00:07.818Z.

Pause start and end dates are visible on:

• /v1.2/districts/<id>/status

Launch date

In 2016, we released a feature allowing applications to Launch district connections—until a connection is launched, users from the district cannot log in using Instant Login. Launch dates are set from the application’s Clever Dashboard.

In v1.1: Launch dates can only be accessed via the Clever Dashboard.

In v1.2: We added launch_date as a field on our status endpoint. The value will be in Date format, e.g. 2017-02-03T14:00:07.818Z.

Launch date is visible on:

• /v1.2/districts/<id>/status

Updated features

District sync status

We’re updating our District Status endpoint so “state” better represents the actual status of district syncs. Possible values for district sync status are now: ["running", "pending", "error", "paused"]. “Pending” means there is an error that the district can fix; “error” means there is an error that Clever can fix; and “paused” means that the district’s sync is paused to reflect last year’s data.

This update is reflected on:

• /v1.2/districts/<id>/status

Deprecated features

v1.2 will not deprecate any features.

Release date

API v1.2 will be officially released on April 4, 2017. On this date, new applications will only be able to use v1.2. From April 4 to June 4, we will fix any bugs we find; on June 5, the existing version will be frozen as is.

Upgrading to v1.2

You can make calls against new versions of the API by updating your URLs (e.g. https://api.clever.com/v1.2/districts). Please note:

• The api.clever.com/me endpoint (primarily used in Instant Login) is for v1.1 only. To receive responses with features from v1.2, you need to update to use api.clever.com/v1.2/me.
• If you are moving an events-based sync to v1.2, you must do a full resync from the Data API to ensure all records in your database are using the correct features prior to using /v1.2/events.

Client Libraries

The majority of our client libraries and code examples have moved to a community-supported model. With the release of API v1.2, we will be releasing new libraries that are v1.2 compatible and are committed to updating these to be compatible with future versions we release. As new libraries are released for v1.2, we will officially deprecate the existing libraries. They will continue to work for v1.1 integrations.

We’re in the process of creating new client libraries that will be compatible with API v1.2! If you’re interested in a client library for your language, in early access to v1.2, or just have a  question, please reach out to us at tech-support@clever.com!