[docs] Add first version of Badges API

Author: sarjona

docs/apis/subsystems/badges/index.md

@@ -0,0 +1,66 @@
+---
+title: Badges API
+tags:
+  - API
+  - Badges
+---
+<!-- cspell:ignore Instructure's -->
+
+The Moodle Badges API facilitates the creation and management of site and course-specific badges, enabling their export to external Open Badges compliant platforms, often referred to as "backpacks".
+
+## Evolution of Open Badges
+
+The **Open Badges** standard, designed to recognize and verify learning achievements, has evolved significantly since its beginning. The **Mozilla Foundation** launched the initial version in 2012 with **Open Badges 1.0** and its "Backpack" platform. Over time, the standard matured, with **Open Badges 2.0** officially released by the **IMS Global Learning Consortium (now 1EdTech**) on April 12, 2018.
+
+Following the release of Open Badges 2.0, Mozilla announced the retirement of its Backpack program in late 2018. This led to a migration to **Concentric Sky's (now Instructure's) Badgr platform**, which started in August 2019. More recently, in April 2022, **Canvas LMS** acquired Concentric Sky, the creators of Badgr.
+
+While many providers support Open Badges 2.0, **Badgr offers a unique API implementation, inherited from Mozilla** (detailed at https://api.badgr.io/swagger-ui/index.html). Moodle directly supports this specific API. This is important because the Open Badges 2.0 specification defines the badge data itself, but not the protocol for interchanging badges.
+
+## Badges data (JSON)
+
+Each badge is represented as a JSON object with the following structure:
+
+```json title="Example Open Badge v2.0/v2.1 JSON"
+{
+  "@context": "https://w3id.org/openbadges/v2",
+  "type": "BadgeClass",
+  "id": "https://example.com/badges/12345",
+  "name": "Example Badge",
+  "description": "This badge represents an example achievement.",
+  "image": "https://example.com/images/badge.png",
+  "criteria": {
+    "narrative": "To earn this badge, you must complete the example task."
+  },
+  "issuer": {
+    "type": "Issuer",
+    "id": "https://example.com/issuers/67890",
+    "name": "Example Issuer",
+    "url": "https://example.com"
+  }
+}
+```
+
+Each version of Open Badges uses its own JSON schema to define the badge's data. Currently, Moodle supports **Open Badges 2.0 and 2.1**, which share the same schema. In the near future, it will also support **Open Badges 3.0**, which has a different schema.
+
+To manage these different versions and their unique requirements, each Open Badge version requires a specific folder structure containing its respective exporters. The structure is as follows:
+
+```none title="Folder structure for Open Badges exporters"
+├── local/backpack/ob/v2p0/
+│   ├── assertion_exporter.php
+│   ├── badge_exporter.php
+│   ├── issuer_exporter.php
+│   ├── recipient_exporter.php
+│   ├── revoked_assertion_exporter.php
+```
+
+The JSON files are generated by calling the exporters located in the respective version folders. They can be accessed from the badges/json/ folder, specified by the version number in the URL. For example, to access the Open Badges 2.0 JSON, you would use:
+
+```none title="Accessing Open Badges v2.0 assertion JSON"
+https://yourmoodlesite.com/badges/json/assertion.php?b=assertionhash&obversion=v2p0
+```
+
+## See also
+
+- [Open Badges Specification v2.0](https://www.imsglobal.org/spec/ob/v2p0)
+- [Open Badges Specification v2.1](https://www.imsglobal.org/spec/ob/v2p1)
+- [Open Badges Specification v3.0](https://www.imsglobal.org/spec/ob/v3p0)

docs/devupdate.md

@@ -17,3 +17,16 @@ The `maxsections` setting in course formats is now deprecated. Previously, this
 Although the `maxsections` setting remains available for now, it is marked as deprecated and will be removed in Moodle 6.0. Also, the `get_max_sections` from `core_courseformat\base` is also deprecated and will be removed in Moodle 6.0.
 
 If your format plugin relies on `maxsections`, you should add a custom setting in your plugin to control section limits. For reference, see the week format plugin, which now uses its own setting for this functionality.
+
+## Badges API reorganisation
+
+<Since version="5.1" issueNumber="MDL-82147" />
+
+The Badges API is responsible for managing badges in Moodle, including their creation, management, and export to external platforms compliant with Open Badges standards. However, the current implementation has become complex and difficult to maintain, and can't be easily extended to support future versions of Open Badges.
+
+To address these challenges, we're reorganising the API to significantly improve its structure and maintainability. Key changes include:
+
+- Re-implementing JSON files to support multiple Open Badges versions (MDL-85621). This will allow for seamless integration with different schema requirements.
+- Reorganizing the Backpack API to support multiple Open Badges versions (MDL-85622). This ensures the API can consistently interact with various backpack standards.
+
+More information about the Badges API can be found in the [Badges API documentation](./apis/subsystems/badges/index.md).