Finalize the API

[encukou]

The API is currently at version 0 ("beta"). It should get some real-world testing before it's finalized.
Documentation is scarce; consult the JSON schema if the meaning of some field is not clear.
If you use the API, please report individual issues or discuss on Slack if something is not right.

If you use the API, please subscribe to this issue to get change notifications.
From version 1 there will be a backwards compatibility promise.

[encukou]

cc @messa @vahalova

[messa]

I've integrated the API with courseware: messa/pyladies-courseware@23105ae

🚀 Already deployed: projekty.pyladies.cz

So far so good 👍

[encukou]

• I'm planning to update all times (not dates) to include the timezone. If you use time info (start/end), see https://github.com/pyvec/naucse.python.cz/issues/525.

[encukou]

API version 0.1 – session.serial

The v0 URLs now serve API version 0.1. There is one backwards compatible change:

Sessions now have 'serial': the “number” of the lesson. This allows things like numbering sessions from zero, like in Brno's Monday course.
The serial is actually a string. It could be e.g. a Roman numeral (like XIV). Don't use it for sorting. It also may be missing, if the session is not to be numbered.

Known consumers:

• projekty.pyladies.cz doesn't number sessions
• zpetnovazebnik.herokuapp.com : https://github.com/vahalova/Zpetnovazebnik/pull/8

(If you want to use this in your course, update naucse_render to 1.2+. See its changelog.)

[encukou]

I'm planning to clean up course slugs – replace slashes by dashes: #12

EDIT: No longer the case.

[encukou]

I'm planning to:

• add an "etag" key to courses: Add an "ETag" to courses to make it easier to detect modifications #33
  • should not break anything; API consumers will need new code to take advantage of this
• disallow duplicate keys (such as session slugs): converters: Disallow duplicate keys in KeyAttrDictConverter #34
  • for input only
• tweak titles in subpages to allow breadcrumbs: API 0.2 preparation; add page subtitles #29
  • should not break current consumers as they don't deal with subpages

[encukou]

API version 0.2

The v0 URLs now serve API version 0.2. Changes:

• Courses now have an etag, which will change when that course is updated. (Add an "ETag" to courses to make it easier to detect modifications #33)

• Pages can now have a subtitle; for example the lesson "Instalace Pythonu" might have a subpage with:

  • title: "Instalace Pythonu – Linux" (as before)
  • subtitle: "Linux"

  (Currently, no courses provide this info. If you want to use this in your course, update naucse_render to 1.3+. See its changelog.)

[encukou]

• Add a extra_lessons key; include all lessons in the course metadata (List all lessons in the input API #43)