Today, we’re announcing some upcoming breaking changes for developers using the Microsoft Graph assignments API. The assignments API enables education users and partners to get and set properties associated with assignments in Microsoft Teams EDU. In addition to removing some properties, methods, and resources, we are improving performance of GET requests, including some updates to how pagination works for GET requests. These changes will be rolling out to the Microsoft Graph beta endpoint on May 17, 2021.
Properties to be removed
What is the change?
The following properties will be removed from the educationSubmission entity.
Why the change?
The release action on a submission is obsolete. As a result, the released state on a submission and any properties associated with it are obsolete.
What do I need to do?
Please update your code to remove references to the properties that will be obsolete.
Method to be removed
What is the change?
The educationAssignment: getResourcesFolderUrl function will be removed.
Why the change?
Because an assignment resources folder is always tied to an assignment, it is more appropriate to expose this as a property of the educationAssignment entity. The name of the new property will be resourcesFolderUrl.
What do I need to do?
Remove any calls to /education/classes/{id}/assignments/{id}/getResourcesFolderUrl. Replace it with a call to GET /education/classes/{id}/assignments/{id} and use the value of the resourcesFolderUrl property in the response.
Example
Microsoft Graph API call before the change
GET /education/classes/{id}/assignments/{id}/getResourcesFolderUrl
Microsoft Graph API call after the change
GET /education/classes/{id}/assignments/{id}
Response containing resourcesFolderUrl:
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#education/classes('955e0bd5-52c2-41ad-b7e8-5b33a18c5e78')/assignments/$entity",
"classId": "955e0bd5-52c2-41ad-b7e8-5b33a18c5e78",
"displayName": "Unit 3 Essay",
…
"resourcesFolderUrl": "https://graph.microsoft.com/v1.0/drives/b!H0Unq6KJREmMLHgbJXfKw4YTuh2luKRDvUVGQBLOmvaRxxvbedZKT4LKslSIjT9a/items/01SMYGQ3IUCDNLBJ4XCFE3AQMQHTLSLVYX",
…
}
Resource types to be removed
What is the change?
The following resource types will no longer be supported as resources that can be attached to assignments and/or submissions:
Why the change?
These resources can’t be created using the Microsoft Graph API. As a result, it doesn’t make sense to support them as resources for assignments.
What do I need to do?
Please update your code to remove any references to the creation or usage of these resources.
Improved GET request performance
What is the change?
The following navigation properties will no longer be implicitly expanded in the educationAssignment entity:
- resources
- submissions
- categories
- rubric
The following navigation properties will no longer be implicitly expanded in the educationSubmission entity:
- resources
- submittedResources
- outcomes
Why the change?
We are making GET APIs on assignments and submissions more efficient by returning a leaner payload by default.
What do I need to do?
If you depend on a specific property that is no longer implicitly expanded in the educationAssignment entity, include an explicit `$expand` for that property on the GET API calls, as shown.
- resources
GET /education/classes/{id}/assignments?$expand=resourcesGET /education/classes/{id}/assignments/{id}?$expand=resources
- submissions
GET /education/classes/{id}/assignments/{id}?$expand=submissions
- categories
GET /education/classes/{id}/assignments?$expand=categoriesGET /education/classes/{id}/assignments/{id}?$expand=categories
- rubric
GET /education/classes/{id}/assignments?$expand=rubricGET /education/classes/{id}/assignments/{id}?$expand=rubric
If you depend on a specific property that is no longer implicitly expanded in the educationSubmission entity, include an explicit $expand for that property on the GET API calls, as shown.
- resources
GET /education/classes/{id}/assignments/{id}/submissions/{id}?$expand=resources
- submittedResources
GET /education/classes/{id}/assignments/{id}/submissions/{id}?$expand=submittedResources
- outcomes
GET /education/classes/{id}/assignments/{id}/submissions/{id}?$expand=outcomes
Pagination changes
What is the change?
For all GET APIs, the default page size will be set to 50. This is the number of entities returned in a GET call if the $top option is not specified. There is no change in behavior if $top is specified.
Why the change?
Currently, the page size is set to a much higher value of 500 and that affects the performance of the GET API.
What do I need to do?
There is no action needed:
- If you are using the
$topoption in the GET API call OR - If you are not using the
$topoption but you are handling pagination in your code (by following the Next link in the response)
There is action needed:
- if you are not using the
$topoption and you are not handling pagination in your code currently (by following the Next link in the response), please add pagination
Assignment and Submission resource folders are not created automatically
What is the change?
Resources can be attached to an assignment and a submission. These resources are stored in a assignment or submission specific resources folder in SharePoint. An assignment resources folder is currently automatically created asynchronously as a side effect of creating a new assignment. A submission resources folder is currently automatically created asynchronously as a side effect of publishing an assignment for every student submission. The change is to stop creating these folders automatically and require the caller to set them up by calling a new API.
Why the change?
Our telemetry over the past year has shown that most assignments do not have resources attached to them. To save on storage and improve API performance, we are disabling implicit folder creation for storing resources.
What do I need to do?
We are working on details of the new APIs that will allow setting up the resource folders. We will be publishing those details in an upcoming blog post. Until then, no action is needed.
Happy coding!
