mDIS User Documentation

REST API Reference (basic)

Open Endpoints

Open endpoints do not require authentication.

Login

  • Login POST /api/v1/auth/login

Reminder

At this time, the Login Screen is the only endpoint that does not require any authentication.

However, its sole purpose is to accept login requests with username and password, and to give out security tokens, enabling the user to proceed to closed endpoints. After successful login, the web server returns a Bearer token in the JSON response:

{
  "username": "sly",
  "token": "...-...",
  "roles": [ "developer" ]
}

(Fragment, simplified)

Endpoints with authentication

"Closed" endpoints require a valid "Bearer Token" to be included in the header of the request. A token can be acquired from the Login response above. The token acts like a temporary password, or as a temporary API key. A benefit of the Bearer token is that the "real" username and password are submitted only once, during login. Later, instead, the token is submitted with each HTTP request.

All endpoints that require authentication return an error response of Unauthorized, HTTP status 401:

{
  "name": "Unauthorized",
  "message": "Your request was made with invalid credentials.",
  "code": 0,
  "status": 401,
  "type": "yii\\web\\UnauthorizedHttpException"
}

However, HTTP status 422 ("Unprocessable Entity") is also returned often, e.g. when invalid filter expressions are used as query string parameters.

A successful authentication response looks like this.

{
  "id": 3,
  "username": "bnk",
  "email": "bnk@example.com",
  "token": "...-...", //temporary password
  "roles": ["_administrator_"],
  "permissions": [
    "form-archive-file:edit",
    "form-archive-file:view",
    "form-cores:edit",
    "form-cores:view",
    "form-init-gas:edit",
    "form-init-gas:view",
    "form-section:edit",
    "form-section:view"
  ]
}

Note that an authentication token was provided, which is valid until it expires, or until the user logs out. The expiration date can be extended simply by reloading any mDIS webpage.

Auth Controller

  • Login POST /api/v1/auth/login - see above
  • Logout POST /api/v1/auth/logout - returns 1 if successful (= Security Token was still valid)
  • Refresh GET /api/v1/auth/refresh

App Controller

This lists the forms created by mDIS admins. The result of this call is used to construct the listing in the sidebar of the mDIS dashboard.

  • Forms GET /api/v1/app/forms

There are no other API endpoints to change the forms listing. However, another useful URI to know is /cg/api/summary, which returns a complex object with keys modules, models, forms which returns read-only metadata (such as the column names) of tables, tablesets (internally named modules), models, and forms.

Global Controller (CRUD controller)

The endpoints under global are used to perform CRUD operations (Create, Retrieve, Update, Delete, Defaults, etc.) for data models under directory /backend/models. Mainly to manage ArchiveFiles and ListValues data models, and also to get data from all columns of the data tables. This is in contrast to the forms controller which only returns the subsets that end users can actually see with that form.

Form Controller

Form is a specialization of global. The endpoints under form are used to manage (create, update, delete, defaults, etc.) data models under directory /backend/forms which inherit from the data models in directory /backend/models. They usually only return a subset of the data.

Example. A form controller URL looks like this:

/api/v1/form?per-page=1000&page=1&sort=core&filter[hole_id]=${hole_id}&&name=core

Substitute the $hole_id with the value of the Primary Key id column for that hole; e.g. if the id for hole 2 of a certain site has the value 15, use filter[hole_id]=15.

List Values Controller

List Values is also a specialization of global, i.e. it contains all the actions in global (except filter-list & reports) and the following extra ones:

  • List Names GET /api/v1/list-values/list-names - Names of Select Lists
  • List Values GET /api/v1/list-values - Values for each Select List

File Controller

Used to manage uploaded files, and to connect or attach them to existing datasets.

  • Index GET /api/v1/file
  • Assign POST /api/v1/file/assign
  • Delete POST /api/v1/file/delete
  • Upload POST /api/v1/file/upload
  • MetaData GET /api/v1/file/meta-data/<name>
  • Unassign PUT /api/v1/file/unassign/<fileId>

Code examples for using these REST API calls with curl can be found in some mDIS-installer scripts for customizing the mDIS dashboard.

TBC Widgets Controller

Dashboard widgets controller, manages visibility, alignment, cloneability.

The code examples mentioned in the previous paragraph demonstrate some calls.

TBC

TBC Importer Controller

CSV file controller, Value List controller.

TBC

TBC Posts Controller

TBC - Dashboard Posts controller

Missing REST API Endpoints

These items do not have a REST API endpoint, or documentation is missing:

  • Reports. There is no ReportsController. Reports can be listed via the Form Controller or the Global Controller though. However, new reports cannot be created via a REST API.
  • Everything covered by the cg-API (see below) has no documentation at this time.
  • User management. Creating users and roles are basically one-off tasks and not very data-intensive. There is no REST API for managing users. (It might still be scriptable with PHP, though)