Purview

I det følgende beskrives (ganske kort) strukturen for det api vi har brug for for at kunne lave den ønskede visning af indhold¹ som brugere skal rydde op i. Api'et skal udstille data fra en databasen som indeholder data baseret på Purview-kørsler.

Begreber

• Applikationen: Den hjemmeside som brugeren skal gå ind på
• Visningen: Præsentationen af brugerens data hentet via api'et. Applikationen sørger for at levere visningen til brugeren. Al kommunikation, fx sletning af indhold, fra visningen til api'et går via applikationen, dvs. vi udstiller ikke api-nøgler mm. for klienten
• Api'et: Derfra hvor al data hentes inden det vises for brugeren

For at holde visning af data skarpt adskilt fra opbevaring af data, vil hverken visningen eller applikationen indholde data, men vil altid hente data fra api'et umiddelbart før det vises.

Adgangsstyring og sikkerhed

• En bruger logger ind i applikationen via AD'et.
  • Applikationen gemmer ikke data om brugeren ud over hvad der er strengt nødvendigt for identificere brugeren og sikre at en bruger kun ser det data den må se.
• Som nævnt ovenfor vil alle api-kald i praksis blive lavet server-til-server, dvs. klienten (visningen) kalder tilbage til moderskibet (applikationen) som så laver det faktiske api-kald.
• Applikationen knytter brugerens id til api-kaldet, fx via en x-username-header

Ønsker til api'et

Vi har brug for at kunne

• hente oplysninger om alt indhold som en bruger skal forholde sig til
• udføre handlinger på et stykke indhold
  • evt. på flere stykker indhold via "massehandling"
• give en leder et overblik over hvordan det står til hos undersåtterne

Derudover vil det være fornuftigt at kunne

• give en bruger et overblik over tingenes tilstand (a la en portalforside).

---

Nedenfor gives nogle eksempler på hvordan data kan leveres fra api'et. Vi henter inspiration fra JSON:API med hensyn til struktur på data leveret, men det er ikke afgørende at vi ender med præcis denne struktur.

For læs- og skrivbarhedens skyld bruges JSON5 i eksemplerne nedenfor, men i praksis skal der bruges JSON.

Alt indhold for en bruger

GET /api/v1/my-stuff

{
  data: [
    {
      // Unik identifikation
      type: "email",
      id: "0dc61832-ccf1-4b1a-8f68-b3d4a31ea5eb",
      // Egenskaber for indholdet
      attributes: {
        label: "Indkaldelse til kammeratlig samtale",
        oprettet: "2001-01-18T07:45:57",
        url: "https://outlook.office.com/item/0dc61832-ccf1-4b1a-8f68-b3d4a31ea5eb",
        // …
      },
      // Handlinger for indholdet. Forskelligt indhold kan have forskellige handlinger
      // og indhold af samme type, fx to emails, kan også have forskellige handlinger.
      actions: {
        delete: {
          label: "Slet",
          url: "/api/v1/item/0dc61832-ccf1-4b1a-8f68-b3d4a31ea5eb/delete",
          method: "DELETE",
          // Hvis brugeren aktiverer "Slet“, laver vi et `DELETE`-kald `/api/v1/item/0dc61832-ccf1-4b1a-8f68-b3d4a31ea5eb/delete`
        },
        postpone: {
          label: "Påmind mig om 30 dage",
          url: "/api/v1/item/0dc61832-ccf1-4b1a-8f68-b3d4a31ea5eb/postpone?days=30",
          method: "PATCH",
        },
        // …
      },
    },
    {
      type: "email",
      id: "fff28419-aaab-42dc-952a-62e1614b701f",
      attributes: {
        label: "Hemmeligt møde",
        oprettet: "2001-03-10T12:45:57",
        url: "https://outlook.office.com/item/fff28419-aaab-42dc-952a-62e1614b701f",
      },
      actions: [
        {
          label: "delete",
          url: "/api/v1/item/fff28419-aaab-42dc-952a-62e1614b701f",
          method: "DELETE",
        },
      ],
    },
    {
      id: "896f6238-3a4b-4c99-bc90-55fc45035a45",
      type: "document",
      attributes: {
        documenttype: "word",
        label: "Referat fra møde",
        oprettet: "2021-01-18T07:45:57",
        url: "https://aarhuskommune-my.sharepoint.com/:w:/…/896f6238-3a4b-4c99-bc90-55fc45035a45",
      },
      actions: [
        {
          label: "delete",
          url: "/api/v1/item/896f6238-3a4b-4c99-bc90-55fc45035a45",
          method: "DELETE",
        },
      ],
    },
  ],
  links: {
    self: "/api/v1/my-stuff",
    next: "/api/v1/my-stuff?page[offset]=2",
  },
}

"Mit overblik“

GET /api/v1/my-overview

{
  data: [
    {
      type: "item",
      id: "email",
      attributes: {
        label: "Emails",
        total: 1021,
        postponed: 876,
        // Henvisning til detaljeret oversigt
        url: "/api/v1/my-stuff?type=email",
        // …
      },
    },
    {
      type: "item",
      id: "document-word",
      attributes: {
        label: "Word-dokumenter",
        total: 123,
        postponed: 76,
        url: "/api/v1/my-stuff?type=document&documenttype=word",
        // …
      },
    },
  ],
}

Leders overblik over medarbejderes udeståender

GET /api/v1/my-people?page[offset]=2

{
  data: [
    {
      id: "menig12345678",
      type: "mand på gulvet",
      attributes: {
        name: "Anders And",
        reports: [
          {
            type: "email",
            total: 1021,
            postponed: 876,
            // …
          },
          {
            type: "document",
            total: 123,
            postponed: 76,
            // …
          },
        ],
      },
    },
    {
      id: "menig56123421349",
      type: "mand på gulvet",
      attributes: {
        name: "Fætter Guf",
        reports: [
          {
            type: "email",
            total: 87,
            postponed: 0,
            // …
          },
        ],
      },
    },
    // …
  ],
  links: {
    self: "/api/v1/my-people?page[offset]=2",
    prev: "/api/v1/my-people?page[offset]=1",
  },
}

Footnotes

1. “Indhold“ dækker her over både e-mails, filer (Word-dokumenter, pdf'er, …) og hvad man ellers har liggende i OneDrive mm. ↩