endpoints-backoffice.md

Backoffice API Requirements

Recommended reading: Microsoft REST API Guidelines

This are the required endpoints for the UA's Portal Backoffice, some of them might already exist.

◀️ Priority 🍑 Next in line

Authentication

All user related logic. Needs to work with a Single Page Application, preferably some JWT solution.

There's also the need for roles, this are my suggestions, they can have different names:

• Admin - access to all endpoints (admin of all subdomains)
• Editor - access to all subweb endpoints (can manage subdomains or specific pages)
• Normal - access to remaining endpoints (can edit specific pages, upload content...)

Admin - access to all endpoints (admin de todos os subdominios) Editor - access to all subweb endpoints (pode gerir subdominios inteiros ou páginas especificas editar/apagar/criar) Normal - access to remaining endpoints (pode editar paginas especificas ou editar subdominios inteiros e fazer upload de conteudo) User - faz login mas não tem acesso a nada

GET /users/auth ◀️

Starts the authentication flow with the UA Identity OAuth protocol.

GET /users/current ◀️

(Normal) Current logged in user from the token (passed through an header, cookie, ...). Has all the necessary user information used for initial application load such as user data, his subwebs...

{
  "data": {
      "_id": "5d2e022beb80ed9bd5f0f5fa",
      "username": "antoniojps",
      "admin": true,
      "moderator": null,
      "email": "antoniojps@ua.pt"
    }
}

GET /users/{id} ◀️

(Normal) User info, maybe use a query string for specific backoffice data for user subwebs, and roles...

{
  "data": {
      "_id": "5d2e022beb80ed9bd5f0f5fa",
      "email": "antoniojps@ua.pt",
      "username": "antoniojps",
      "name": "António",
      "surname": "Santos",
      "providers": [
        {
          "id": "c3c63153-4b08-4f8e-a01f-b75bc1096cf2",
          "provider": "identityua"
        }
      ],
      "avatar": null,
      "admin": true,
      "moderator": null,
      "createdAt": null,
      "updatedAt": null
    }
}

Good to have:

GET /users?...

(Normal) Provide filtering, sorting, field selection, paging if possible.

Subwebs

Manipulate subwebs, their pages and users.

GET /subwebs ◀️

(Normal) Subwebs list

GET /subwebs/{id}

(Normal) Subweb info

POST /subwebs/{subweb}

(Admin) Create a new subweb

PUT /subwebs/{subweb}

(Admin) Edit subweb (name, ...)

DELETE /subwebs/{subweb}

(Admin) Archive a subweb

POST /subwebs/{subweb}/users/{id}

(Editor) Add normal user to subweb with default role (Normal)

POST /subwebs/{subweb}/users/{id}/roles/{role}

(Editor) Add user to subweb with a specific role

DELETE/subwebs/{subweb}/users/{id}

(Editor) Remove user from subweb

DELETE /subwebs/{subweb}/users/{id}/roles/{role}

(Editor) Remove user role from subweb (if no other role the user is removed)

GET /subwebs/{subweb}/content/{id} ◀️

(Public) Page JSON data

PUT /subwebs/{subweb}/content/{id} ◀️

(Editor) Edit page

POST /subwebs/{subweb}/content ◀️

(Admin) Create page

DELETE /subwebs/{subweb}/content/{id} ◀️

(Admin) Archive page

GET /subwebs/{subweb}/content/{id}/versions

(Normal) Pages available versions (dates, version id,...)

GET /subwebs/{subweb}/content/{id}/versions/{id}

(Normal) Page JSON data of specific version

PATCH/PUT /subwebs/{subweb}/content/{id}/versions/{id}

(Editor) Roleback page to specific version

Images

Manipulate and manage images: upload, resize and list

GET /image/{id} ◀️

(Public) Get original image size

GET /image/{id}/resize?height=300 ◀️

(Public) Resize image, with height and width filters

POST /image ◀️

(Normal) Upload image, with alternative text if possible