Breaking change to the grades API?

Development
#1

We recently discovered what we would consider a breaking change to the grades API, which was part of the Juniper release. Before the change, the API returned the email addresses of students in the course. After the change, it only returned email addresses if the course is part of a masters program.

We have a few questions:

  1. Is this a breaking change?

It felt like a breaking change to us. It broke an integration with the API which was expecting to use student’s email addresses as a key.

  1. If this is a breaking change, how should it have been communicated?

The open edX proposal to use conventional commit messages specifies that a commit with a breaking change should include an exclamation mark in the commit message subject. Is that sufficient?

Should breaking changes be included in release notes? How?

  1. Is there anything we should do to communicate this particular change now?

This change was part of the Juniper release, which isn’t even officially supported any more. But, now that we know this change was made, should it be noted somewhere? Is there someplace that interested parties might find it more easily than this thread?

Thanks for your thoughts,
Peter Pinch
MIT Open Learning

#2

My thoughts:

#1. Yes, I would consider this a breaking change. The API contract of the content it includes in its response has changed.

#2. Business-driven APIs should not be broken. These APIs can be expanded to include more data in their response, but not less. If the API needs to evolve to reduce its response content, then that change needs to be included in its next version (v2), with v1 going through the DEPR process.

In this particular case, it seems the change could have been supported, without incrementing the version number, by including an API “filter” parameter that filters for only masters courses.

#3. Is there anyone impacted by this today? Since your posting this thread, it looks like you are. In that case, you could post a PR to correct this issue - for example, adding a “filter” parameter.

Moving forward, to prevent this type of breakage of “business-driven APIs”, we can do a few things:

a. Implement consumer-based contract testing - so API developers know which of their APIs are consumed externally and can get automated feedback on inadvertent breakage.

b. Annotate/classify/namespace/etc our APIs so it’s clear where they belong in the proposed trichotomy.

c. Yes, conventional commit messages will also help remind developers of the impact of their changes.