REST API¶

Base URL¶

/local/middag/index.php/api/v1/

In Moodle 5.1+, friendly URLs via r.php are also available.

Authentication¶

JWT Token¶

Pass a JWT token in the Authorization header:

Authorization: Bearer {token}

Web Service Token¶

Pass a Moodle web service token in the header or query string:

Authorization: {token}

GET /local/middag/index.php/api/v1/items?wstoken={token}&type=course

Tokens are created in Site administration > Server > Web services > Manage tokens.

Moodle Session¶

Requests from logged-in browser sessions use the Moodle session automatically. Write operations (POST, PUT, DELETE) require sesskey.

Content-Type¶

All requests and responses use:

Content-Type: application/json

Enabling the API¶

The REST API is disabled by default. To enable:

Set mdg_core_api_enabled to true via Site administration > Plugins > Local > MIDDAG > Settings
Optionally set mdg_core_api_openapi_public to true to expose the OpenAPI spec without authentication

While disabled, all /api/* endpoints return 403.

Endpoints¶

Items (Generic CRUD)¶

All registered Item types are accessible via the same endpoints. The type parameter determines which entity is queried.

Method	Path	Description
`GET`	`/api/v1/items?type={type}`	List items with filters and pagination
`POST`	`/api/v1/items`	Create a new item
`GET`	`/api/v1/items/{id}`	Get item by ID
`PUT`	`/api/v1/items/{id}`	Update item (partial)
`DELETE`	`/api/v1/items/{id}`	Delete item
`GET`	`/api/v1/items/{id}/metadata`	Get item metadata

Query Parameters (GET /api/v1/items)¶

Parameter	Type	Required	Description
`type`	string	Yes	Item type (e.g., `course_group`, `company`)
`page`	integer	No	Page number (default: `0`)
`perpage`	integer	No	Items per page (default: `20`)
`filters`	string (JSON)	No	Metadata filters (e.g., `{"status":"published"}`)

Response Format¶

Success¶

{
  "success": true,
  "data": [
    {
      "id": 1,
      "type": "course_group",
      "fullname": "Excel Training 2024",
      "status": "published",
      "metadata": {
        "sku": "EX-2024",
        "hours": 40
      }
    }
  ],
  "meta": {
    "total": 15,
    "page": 0,
    "pages": 8
  }
}

The metadata field returns dynamic metadata defined by the Item type. When the type declares metadata_schema(), fields are typed according to the entity definition.

Error¶

{
  "error": true,
  "message": "Validation failed",
  "code": 422,
  "errors": {
    "type": [
      "The type field is required."
    ],
    "fullname": [
      "The fullname field must be a string."
    ]
  }
}

Field	Type	Description
`error`	boolean	Always `true` on error
`message`	string	Human-readable error description
`code`	integer	HTTP status code
`errors`	object	Field-level validation errors (present on 422)

Standard HTTP status codes:

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request
`403`	Forbidden
`404`	Not found
`422`	Validation error
`500`	Internal server error

Extension Endpoints¶

Extensions can register additional endpoints beyond the generic CRUD. These endpoints appear automatically in the OpenAPI specification.

OpenAPI Specification¶

Runtime endpoints (reflect the current installation):

Format	URL
JSON	`/local/middag/index.php/api/openapi.json`
YAML	`/local/middag/index.php/api/openapi.yaml`

The runtime spec includes all Item types and extension endpoints registered in the active Moodle installation.

Public Access¶

By default, OpenAPI endpoints require authentication. To allow public access:

Set mdg_core_api_openapi_public to true via admin settings.

CLI Generation¶

Generate a static spec file:

php cli/build.php --openapi
php cli/build.php --openapi --format=json
php cli/build.php --openapi --server-url=https://example.com/local/middag
php cli/build.php --openapi --dry-run