Bruksanvisning för användnings-API och beskrivning av REST-gränssnittet

Allmänt

Med hjälp av användningsgränssnittet kan man använda det digitala informationsmaterial som förvaras i Riksarkivet samt den beskrivande kontextuella metadatan som hör till detta.
De administrativa förutsättningarna beskrivs närmare på webbplatsen för Riksarkivets tjänst för elektronisk arkivering: https://kansallisarkisto.fi/sv/efter-overforingen .
Den här bruksanvisningen innehåller instruktioner om hur du ansluter till användningsgränssnittet och hur du använder användingsgränssnittet.
Användningen sker via suomi.fi-informationsleden, som har sina egna anvisningar.

Det informationsmaterial i förvaringsfas som har överförts till Sapas förvaltning kan göras tillgängligt med hjälp av datasets på serienivå. Vid informationsöverföringen används Suomi.fi-informationsleden. Riksarkivet ansvarar i åtkomsthanteringen för att ett delsystem som är kopplat till kundorganisationens anslutningsserver endast får tillgång till den information som har licensierats för just detta delsystem. Den tjänsteanvändande organisationen styr själv vem som beviljas visningsrätt till det egna materialet.

Datauppsättningar

En datauppsättning är en kund definierad informationshelhet som anger vilka delar av informationsmaterialet som finns tillgängliga för sökning och distribution. En datauppsättning innehåller delmängder av informationsmaterialet med arkivenheter och underenheter.

Med hjälp av en datauppsättning är den möjligt att använda och vidareförädla materialet för egna behov samt dela den vidare till tredje parter.

Informationen kan användas via SAPA eller laddas ner som en JSON-fil. JSON-filen som beskriver datauppsättningen kan laddas ner antigen vi Sapas användargränssnittet eller via gränssnittet. Tillhörande filer är tillgängliga via gränssnittet kräver en separat API-nyckel, och för att skapa denna nyckel samt hämta datauppsättning krävs att gränssnittsförmedlarens roll är tilldelad i SAPA. Dessutom måste tjänsten för digital användning ge tillstånd för datauppsättningen till den eller de valda personerna. I vyn “Mina API-nycklar“ kan du granska de datauppsättning som har skapats för din användning och om du vill, ladda ner dem till din dator.

En datauppsättning har en begränsad giltighetstid på ett år. Riksarkivet påminner kundorganisationen om att datauppsättningen håller på att förfalla och vidtar nödvändiga åtgärder om den finns skäl att förlänga giltighetstiden.

Användningsprocessen i sin helhet

Figuren nedan visar den operativa processen för användningen.

De här instruktionerna beskriver hur du går tillväga i de olika stegen och ger mer information om de tillgängliga gränssnittsobjekten, det vill säga endpoints, och kraven för dem.

Administrativa frågor

I det följande antas att anslutning till Suomi.fi-informationsleden har etablerats, att de förberedande/administrativa faserna för användning har genomförts och att man i de adminisrativa förberedelserna har valt att använda gränssnitt. I de administrativa faserna har det redan klargjorts vilken materialet som kommer att användas via gränssnitten.

För mer information om administrativa processer och avtal, se Instruktionsbanken på Riksarkivets webbplats: https://kansallisarkisto.fi/sv/instruktionsbank#digitalarkivering

Skapning av ett datauppsättning

Riksarkivet skapar en datauppsättning som täcker den överenskomna serien och de önskade uttryckstyperna. När datauppsätningen har skapats får den behöriga personen ett meddelande om detta via e-post. Efter meddelandet kan användaren gå till SAPA-gränssnittet för att hämta en API-nyckel.

Hämta Api-nycklar

API-nycklar hämtas i överföringsgränssnittet. Förutsättningen för att hämta en API-nyckel är att du under den administrativa fasen har tilldelats rätt roll i överföringsgränssnittet av Riksarkivet. För användning av gränssnitt krävs dessutom att en datauppsättning har skapats för användaren.

Slutförande och hämtning av datauppsättningen

När en API-nyckel har skapats för att använda datauppsättningen, måste datauppsättningen slutbehandlas av Riksarkivet innan dess information kan hämtas via användargränssnittet eller gränssnittet. Du får ett e-postmeddelande när slutbehandlingen av datauppsättningar är klar.

Datauppsättnings användningsexemplar hämtas från gränssnittet för användningsexemplar. Materialet är alltid licensierat på serienivå. Hämtning av datauppsättningen förutsätter att det först har skapats enligt instruktionerna i föregående avsnitt.

Via Sapas användningsgränssnittet

Logga in i Sapas användargränssnitt och gå till sidan “Mina API-nycklar“.
Klicka på knappen Ladda datauppsättningen. Detta öppnar datauppsättningars information i en ny flik.
Spara datauppsättningens information
Spara datauppsättningens information i ditt eget system.

Via Informationsleden

Instruktioner för hur du hämtar datauppsättningens information via REST-gränssnittet hittar du längre ner under beskrivning av REST-gränssnittet.

Beskrivning av REST-gränssnittet

I det här avsnittet presenteras hur datauppsättningen hämtas via gränssnitt för användning i egna system.

Den aktuella REST-API-beskrivningen i OpenAPI-format finns i Suomi.fi-anslutningskatalogen

Test: Tjänsten för digital arkivering - ws - Informationsledens testmiljö

Produktion: Tjänsten för digital arkivering - ws - Informationsleden

Presentation av datauppsättningens uppgifter på serienivå → GET /api/latest/datasets/series/<document_id>

Med denna funktion presenteras en enskilt datauppsättnings material på serienivå. För att använda funktionen krävs behörighet att hämta och läsa egna datauppsättningen. Document_id kan hämtas från användargränssnittet på sidan “Mina API-nycklar”.

Bestämningar för meddelandet

document_id - Datauppsättningens unika identifierare i SAPA

Returmeddelande i normala situationer

HTTP 200 OK - Ett lyckat meddelande, som svar returneras seriens data från det hämtade datauppsättningen i JSON-format
HTTP 400 Bad Request – Meddelandet stöder inte parametrarna.
HTTP 403 Forbidden – Åtkomst nekad, användaren har inte behörighet att komma åt den här resursen.
HTTP 404 Not Found – Datauppsättningen finns inte.
HTTP 405 Method Not Allowed - Fel metod används i meddelandet (annan än POST).

Textstomme för ett korrekt returmeddelande

CODE

{
  "data": {
    "dataset_id": "1234567890"
    "series": {
      "content_level": "Underenserie"
      "metadata" : {
        "access_restrictions": {
          "template_identifier": "100932679",
          "authorizing_entity": "101498744"
        },
        "confidentiality_class": "Julkinen",
        "content_category": "Viranomaisaineisto-arkistovaihe",
        "content_dates_end": "2024-uu-uu",
        "content_dates_start": "2024-uu-uu",
        ...
      },
      "volumes": {
        "content_level": "Arkivenheter",
        "derivatives": [
          {
            "access_type": "diary_dump_hq",
            "checksum": {
              "algorithm": "md5",
              "hash": "24d88f5e17e1ea4b0071ee341e44c99e"
            },
            "datetime": "2024-05-30T08:22:00.765000+00:00",
            "download": "/api/latest/derivatives/objects/3602021692/download",
            "filename": "0001.csv",
            "filesize": 96176
          },
          ...
        ],
        "metadata": {
          ...
        },
        "subvolumes": {
          "content_level": "Underenheter",
          "derivatives": [
            ...
          ],
          "metadata": {
            ...
          }
        }
      }
    }
  },
  "status": "success"
}

Nedladdning av användningskopia → GET api/latest/derivatives/objects/<object_id>/download?<parameters>

Med denna funktionen kan en användningskopia laddas ner. För att använda funktionen krävs behörighet att läsa användningskopior. Object_id finns i datauppsättningens JSON-fil under avsnittet “derivatives“.

Bestämningar för meddelandet

object_id - Identifierare för användningskopian
<parameters> - I frågan kan följande parametrar anges för att filtrera resultatmängden:
- userid - En parameter som anger användarens identifierare. Identifieraren används för att kontrollera om användaren har tillstånd att använda det aktuella materialet.
- usertype - En parameter som anger användartypen, till exempel en Virtu-användare. Typen används för att kontrollera om användaren har tillstånd att använda det aktuella materialet.
- ip - En parameter som anger begärans IP-adress. IP-adressen används för att kontrollera om användaren har tillstånd att använda det aktuella materialet, när materialets licensiering kräver användning av en betrodd miljö.
- requestid - Ett identifierare som skapats av Astia-systemet, vilket unikt identifierar begäran i Astia.

Returmeddelande i normala situationer

HTTP 200 OK – Ett lyckat meddelande, som svar returneras användningskopian i den filformat som angivits. Filformatet anges i meddelandets rubrik i fältet content-type.
HTTP 400 Bad Request – Meddelandet stöder inte parametrarna.
HTTP 403 Forbidden – Åtkomst till användningskopian är förbjuden, användaren har inte rättigheter till användningskopian.
HTTP 404 Not Found – Användningskopian finns inte.
HTTP 405 Method Not Allowed – Fel metod används i meddelandet (annan än POST).
HTTP 410 Gone – Användningskopian har tagits bort från AHAA-tjänstens metadatan.
HTTP 500 Internal Server Error – Ingen kontakt kunde upprättas med externa tjänster för att kontrollera användarbehörigheter och åtkomstbegränsningar.