Search code examples
apicanvas-lms

Missing enrollment terms in Canvas LMS API

I am currently doing some work with the Canvas LMS REST API and have run into an issue when trying to retrieve a list of all enrollment terms defined in the system. When viewing the terms in the online system, I can see all the terms that have been created, from the first ones up to the furthest defined semester. However, when I try to get a list of terms using

GET /api/v1/accounts/:account_id/terms

I only receive a list of 10 terms, while the rest are missing. Does anyone know what could be causing this?

Additionally, is there a difference between a Term and an EnrollmentTerm object? I only see API calls for EnrollmentTerm objects, while a Term seems to be a subset of the data contained in an EnrollmentTerm that only gets passed within a Course. Could someone explain if there is an important difference here, and what I may be missing?

Lastly, could anyone point me towards some information about error codes that are returned from an API call? For example, when I use

POST /api/v1/accounts/:account_id/terms

with some associated parameters, I get a 400 bad request response. When the parameters are incorrectly named, I get a 500 response instead. Any guidance on this matter would be very helpful.

Let me know if there is anything I can do to help clarify things. Thanks for your help!

Solution

  • I got into contact with Canvas developers and found out that this was caused by how they paginate their API responses. Their default cap appears to be at 10 per response, but this can be extended up to 100 by adding ?per_page=100 at the end of the query like so:

    POST /api/v1/accounts/:account_id/terms?per_page=100

    Additional pages can be retrieved using the URLs returned in the Link header of the response. More info on that can be found here.

    An example Link header would be:

    <https://<canvas>/api/v1/accounts/:account_id/terms?page=1&per_page=10>; rel="current",
<https://<canvas>/api/v1/accounts/:account_id/terms?page=2&per_page=10>; rel="next",
<https://<canvas>/api/v1/accounts/:account_id/terms?page=1&per_page=10>; rel="first",
<https://<canvas>/api/v1/accounts/:account_id/terms?page=10&per_page=10>; rel="last"

    The URLs in the Link header are only included when they are relevant, so the first page will not return a "prev" link and the last page will not return a "next" link, for example.