Basic version of course & progress API

[cliftonc]

@mcginkel this is a very rough version of a course and results API, we need to decide how to best reflect the CMI5 structure in here, as duplicating it into OpenAPI may be sensible, but I haven't done it as yet - figured we needed a starting point for this one so others can also weigh in.

Scopes / Security:

The security for this API is similar to the SIS, in that it requires authorisation at school level via a setup flow - it is enabling the sharing of results between platforms, we need to ensure that it is approved. This also has the side benefit of ensuring that the LA can provide access to specific courses / assignable units that may be specific to a given school (e.g. created by teachers within that school within the LA).

Courses:

• The catalogue that is available to other ecosystem members provides the core list of products that can be purchased, and of course links to the streams (https://stichtingsem.stoplight.io/docs/sem-technology-prototype/reference/catalogue.v1.yaml/components/schemas/Product) related to the product.
• Based on a Stream ID from the catalogue you can then request a list of courses related to that from this Course API.
• The /courses API is intended to be used to retrieve what is available for a specific course based on stream ID, this can return multiple results - these are json and are references to the courses available, this could be used to build the UX to find / use courses in an LMS.
• The /courses/{id} API retrieves a specific course - and this would respond with the CMI5 course specification.

Results:

• It is intended that the LMS create a webhook subscription to receive the XAPI statements via that route, but I have also defined two API's to enable it to be 'caught up' (up for discussion).
• /courses/{id}/results: Get all statements (paginated) for a specific course.
• /student/{id}/results: Get all statements (paginated) for a specific user.

[mcginkel]

Clifton. I miss a level between course and results: arrangement The course is more static like "biologie_voor_jou.vwo-4". This gives the basic course/method that is provided by the product. A product can give acess to multiple methods, and a method can be part of multiple product. A product is more a sellable unit with an EAN, the course is the real thing.

"The /courses API is intended to be used to retrieve what is available for a specific course based on stream ID, this can return multiple results - these are json and are references to the courses available, this could be used to build the UX to find / use courses in an LMS."

I here is where I miss the level: The method/course is identified by the streamcode. There is only one method course. (in time you get versions, but that is a different story) There could be several "arrangements" of the course, a default arrangement or special arrangements from a teacher (based on the same method/course)

I would suggest the following api: /stream/ --> give more information on the stream (biologie voor jou, for vwo-4, latest version etc etc) in JSON /stream//metacontent --> gives the CMI5 format /stream/{streamcode}/courses --> gives all arrangements and default arrangement /courses/{courseid} --> this would respond with the CMI5 course specification for the arrangement

/courses/{id}/results: Get all statements (paginated) for a specific course.

finally /student/{id}/results is not scoped to a period or course, so is not fine-grained enough. Is /courses/{id}/student/{id}/results more clear ?

WDYT?

[cliftonc]

I think we have different understandings of the term arrangement.

1. I agree there is one method course.
2. Arrangements exist within the method course - they are 'assignable units' within it.
3. Arrangements can contain (or be) anything - a collection of excercises, some theory and excercises, a test, a quiz etc.
4. They can be (but dont have to be) grouped into blocks such as Chapters.

Here is a WIP example: https://gist.github.com/cliftonc/8692af67d99d09f03e7114f7b5d2fed1

So what is the difference in response between /stream/metacontent and /courses/{courseid}?

I also recognise that for many Learning Applications the actual thing that is shared may be very different (e.g. a traditional method from a publisher vs a stand alone platform Quizlet vs a collection of items from LessonUp) - so the question of what a block or au actually represents can be very different across LAs - this needs to account for that.

[cliftonc]

@edwinverwoerd I think if we change it here we really need to also change it in the catalogue API. My strong preference is to keep these API's internally consistent, and if we agree to bring all of the SEM definitions closer to the ECK ones at a later stage then we change them everywhere.

[cliftonc]

@mcginkel we have a blocking issue here.

OpenAPI 3.1 does allow XML to be specified, but it is not via XSD, and doesn't offer complete coverage; the biggest issue is that it does not allow non-object types (e.g. string) to have attributes, so you can't represent:

 <langstring lang="nl-NL">17 DNA</langstring>

Options:

1. Use JSON as the format, but use the CMI5 structure (so we ditch the XML)
2. Use XML as the format, but just specify it in the API spec as an object (no properties) and soft-link to the XSD. Code generation would not work for that endpoint.

My preference is 1, but then we move away from the standard - let me know what you prefer?