FINTLabs API

https://fintlabs.github.io/api
Admin
FINTLabs API documentation offers comprehensive guidelines for understanding, accessing, and...
Tokens:5,138
Snippets:23
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Fetch Protected FINT Resource with Authentication (Bash)

Source: https://fintlabs.github.io/api/tools

The fint-curl script fetches a protected FINT resource. It handles obtaining a bearer token using client credentials from a client.json file and then makes the authenticated API request. It requires 'curl' and 'jq' to be installed and has OS-specific 'stat' commands.

```bash
#!/bin/bash

#set -x

if ! ( curl --version > /dev/null && jq --version > /dev/null)
then
	echo "Required tools curl and jq not installed"
	exit 1
fi

case $(uname -s) in
	Linux) 
		STATSZ="stat -c %s"
		STATMT="stat -c %Y"
		;;

	Darwin)
		STATSZ="stat -f %z"
		STATMT="stat -f %m"
		;;

	*)
		echo "Unknown OS $(uname -s)"
		exit 1
		;;
esac

CLIENT=${CLIENT:-client.json}
TOKEN=${CLIENT}.token

if [[ ! -e $CLIENT ]]
then
    echo "Client settings missing"
    exit 1
fi

eval $(cat $CLIENT | jq -r  "\"OAUTH_ID=\"+.clientId, \"OAUTH_SECRET=\"+.openIdSecret, \"OAUTH_USER=\"+.username, \"OAUTH_PWD=\"+.password, \"SCOPE=\"+.scope, \"IDP_URL=\"+.idpUri, \"ASSET_ID=\"+.assetId")

if [[ ! ( -e $TOKEN ) || $($STATSZ $TOKEN) -lt 10 || ( $(( $(date +%s) - $($STATMT $TOKEN) )) -gt 3500 ) ]]
then
    curl -f -s ${IDP_URL:-https://idp.felleskomponent.no/nidp/oauth/nam/token} -u "${OAUTH_ID}:${OAUTH_SECRET}" -d grant_type=password -d username="${OAUTH_USER}" -d password="${OAUTH_PWD}" -d scope="${SCOPE:-fint-client}" | jq -r '.access_token' > $TOKEN
fi

if [[ $($STATSZ $TOKEN) -lt 10 ]]
then
	echo "Authorization failure"
	exit 1
fi

curl -H "Authorization: Bearer $(cat $TOKEN)" -H  "accept: application/json;charset=UTF-8" -H "Content-Type: application/json" -H  "x-org-id: ${ASSET_ID:-fintlabs.no}" -H  "x-client: ${OAUTH_USER}" $*
```

--------------------------------

### API Pagination Example (JSON)

Source: https://fintlabs.github.io/api/overview

Demonstrates how to paginate API results using 'size' and 'offset' query parameters. The response includes links for 'next' and 'prev' pages, along with total item count, current size, and offset. This is useful for handling large datasets efficiently.

```json
{
    "_links": {
        "self": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=0"
            }
        ],
        "next": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=25000"
            }
        ]
    },
    "total_items": 123456,
    "size": 25000,
    "offset": 0
}
```

```json
{
    "_links": {
        "self": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=100000"
            }
        ],
        "prev": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=75000"
            }
        ]
    },
    "total_items": 123456,
    "size": 23456,
    "offset": 100000
}
```

--------------------------------

### FINT API - Get All Objects of a Class

Source: https://fintlabs.github.io/api/overview

This operation retrieves all instances of a specified class from the FINT cache. It returns a JSON object containing a list of entries under '_embedded._entries', along with pagination details and links. The structure is consistent for all main classes in the FINT information model.

```json
{
    "_embedded": {
        "_entries": [
            {
                
            },
            {
                
            }
        ]
    },
    "_links": {
        "self": [
            {
                "href": "..."
            }
        ]
    },
    "total_items": 111,
    "size": 111,
    "offset": 0
}

```

--------------------------------

### Get Objects Updated Since Timestamp

Source: https://fintlabs.github.io/api/overview

Retrieves a collection of objects that have been updated (added or modified) after a specified timestamp. Supports pagination and `size=0` for no updates.

```APIDOC
## Get objects updated since timestamp

`/domain/package/class?sinceTimeStamp=<time>`, i.e. `/administrasjon/personal/personalressurs?sinceTimeStamp=1559551091034`

Returns a collection of all objects that have been updated (added or modified) later than the provided timestamp. The response looks like this:

```json
{
    "_embedded": {
        "_entries": [
            {
                
            },
            {
                
            }
        ]
    },
    "_links": {
        "self": [
            {
                "href": "..."
            }
        ]
    },
    "total_items": 24324,
    "size": 2,
    "offset": 0
}
```

If `size` is `0`, this indicates that there are no new updates since the given timestamp.
This request can also be combined with pagination using `size` and `offset` in case a large number of items have been updated.
**Note:** When FINT API restarts, all items are regarded new. This means a `sinceTimeStamp` parameter from before the restart will return all items. It is therefore recommended to use pagination as well if the result is large.

### Query Parameters
- **sinceTimeStamp** (string) - Required - A timestamp (in milliseconds since epoch) to filter updates.
- **size** (integer) - Optional - Number of items to return. Limits the response to contain maximum `size` elements.
- **offset** (integer) - Optional - Position in list to start returning items from. Skips `offset` items.

### Example
`GET /administrasjon/personal/personalressurs?sinceTimeStamp=1559551091034&size=10&offset=0`
```

--------------------------------

### Get Cache Size (JSON Response)

Source: https://fintlabs.github.io/api/overview

Returns the current size of the cache for a specific class. The response is a simple JSON object containing a single key 'size' with the cache size as its value. This is useful for monitoring and performance tuning.

```json
{
  "size": 10632
}
```

--------------------------------

### Get Objects Updated Since Timestamp (JSON Response)

Source: https://fintlabs.github.io/api/overview

Retrieves a collection of objects that have been updated (added or modified) since a specified timestamp. The response includes embedded entries, links, total item count, size, and offset, supporting pagination for large update sets.

```json
{
    "_embedded": {
        "_entries": [
            {
                
            },
            {
                
            }
        ]
    },
    "_links": {
        "self": [
            {
                "href": "..."
            }
        ]
    },
    "total_items": 24324,
    "size": 2,
    "offset": 0
}
```

--------------------------------

### Get Last Updated Timestamp (JSON Response)

Source: https://fintlabs.github.io/api/overview

Provides the timestamp indicating when the cache for a given class was last updated. The response is a JSON object with a 'lastUpdated' key, holding the timestamp as a string. This helps in determining data freshness.

```json
{
  "lastUpdated": "1559551091034"
}
```

--------------------------------

### Creating New Objects

Source: https://fintlabs.github.io/api/updating

Use the POST method to create new objects. The request body must be a complete resource, including links to other resources.

```APIDOC
## Creating New Objects

### POST /domain/package/class

Use the POST method to create new objects in the FINT API.

### Method

POST

### Endpoint

`/domain/package/class`

*Example:* `/administrasjon/personal/fravar`

### Request Body

- **resource** (object) - Required - The complete resource object to be created, including `_links` to other resources.
  - *Note*: Internal identifiers controlled by the backend system can be omitted.
```

--------------------------------

### Pagination of Results

Source: https://fintlabs.github.io/api/overview

This endpoint supports pagination using `size` and `offset` query parameters to manage large sets of resources. The response includes links for next/previous pages and the total number of items.

```APIDOC
## Pagination of result (`size` and `offset`)

For areas where there are a large number of resources, the API supports pagination. This is controlled by two query parameters:

| parameter | description  
---|---
`size` | Number of items to return. Limits the response to contain maximum `size` elements.  
`offset` | Position in list to start returning items from. Skips `offset` items.  

The response contains `prev` or `next` entries within `_links` if there are more items either before or after (or both) compared to the current page.
The `total_items` attribute in the response can also be used to determine number of requests required.

**Example: 25,000**
Fetch first page: `/administrasjon/personal/person?size=25000&offset=0`

First 25,000 elements are returned. The response contains the following:

```json
{
    "_links": {
        "self": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=0"
            }
        ],
        "next": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=25000"
            }
        ]
    },
    "total_items": 123456,
    "size": 25000,
    "offset": 0
}
```

Keep following the `next` link as long as it’s present, for a total of five requests.
Each response will indicate 123,456 total items. The first four responses will have a `size` of 25,000, but the last response will have a size of 23,456 and no `next` link:

```json
{
    "_links": {
        "self": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=100000"
            }
        ],
        "prev": [
            {
                "href": "/administrasjon/personal/person?size=25000&offset=75000"
            }
        ]
    },
    "total_items": 123456,
    "size": 23456,
    "offset": 100000
}
```

### Query Parameters
- **size** (integer) - Optional - Number of items to return. Limits the response to contain maximum `size` elements.
- **offset** (integer) - Optional - Position in list to start returning items from. Skips `offset` items.
```

--------------------------------

### Fetch Individual Item by Identifier

Source: https://fintlabs.github.io/api/overview

Retrieves a specific item by providing its identifier field name and value. This is useful for accessing individual resources directly.

```APIDOC
## Fetch individual item by identifier

`/domain/package/class/field/value`, i.e. `/administrasjon/personal/personalressurs/ansattnummer/123456`

Given an identifier field name (any field of type `Identifikator`) and the identifier value, try fetching the individual item.

### Endpoint
`/domain/package/class/field/value`

### Example
`GET /administrasjon/personal/personalressurs/ansattnummer/123456`
```

--------------------------------

### GraphQL API Endpoint

Source: https://fintlabs.github.io/api/graphql

The FINT GraphQL API is available at `/graphql/graphql`. It supports POST requests and requires the same Bearer token as other FINT APIs. It's recommended to use a client like Insomnia.rest for testing, which can fetch the schema and validate queries.

```APIDOC
## POST /graphql/graphql

### Description
This endpoint allows you to query FINT data using GraphQL. It requires a Bearer token for authentication.

### Method
POST

### Endpoint
/graphql/graphql

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Body
- **query** (string) - Required - The GraphQL query string.
- **variables** (object) - Optional - A JSON object containing variables for the query.

### Request Example
```json
{
  "query": "query ($ansattnummer: String) {\n  personalressurs(ansattnummer: $ansattnummer) {\n    person {\n      fodselsnummer {\n        identifikatorverdi\n      }\n      navn {\n        fornavn\n        etternavn\n      }\n    }\n    arbeidsforhold {\n      ansettelsesprosent\n      arbeidssted {\n        organisasjonsKode {\n          identifikatorverdi\n        }\n        organisasjonsnavn\n      }\n    }\n  }\n}",
  "variables": {
    "ansattnummer": "12345"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the result of the GraphQL query.
- **errors** (array) - Contains any errors encountered during query execution.

#### Response Example
```json
{
  "data": {
    "personalressurs": {
      "person": {
        "fodselsnummer": {
          "identifikatorverdi": "12345678901"
        },
        "navn": {
          "fornavn": "Ola",
          "etternavn": "Nordmann"
        }
      },
      "arbeidsforhold": [
        {
          "ansettelsesprosent": 100,
          "arbeidssted": {
            "organisasjonsKode": {
              "identifikatorverdi": "974712345"
            },
            "organisasjonsnavn": "Fint Labs"
          }
        }
      ]
    }
  }
}
```
```

--------------------------------

### GraphQL Query for Student Information

Source: https://fintlabs.github.io/api/graphql

This GraphQL query fetches a student's contact information, school, and home address using their FEIDE name. It requires a `String` variable for `feidenavn`.

```graphql
query ($feidenavn: String) {
  elev(feidenavn: $feidenavn) {
    kontaktinformasjon {
      epostadresse
      mobiltelefonnummer
    }
    elevforhold {
      skole {
        navn
        organisasjon {
          organisasjonsnavn
        }
      }
    }
    person {
      navn {
        fornavn
        etternavn
      }
      bostedsadresse {
        adresselinje
        postnummer
        poststed
      }
    }
  }
}
```

--------------------------------

### Obtain Bearer Token using curl

Source: https://fintlabs.github.io/api/accessing

This snippet demonstrates how to obtain a Bearer token from the FINT IDP using `curl` with the OAuth 2.0 Resource Owner Credentials Flow. It requires setting environment variables for IDP URL, client credentials, username, password, and scope. The output `access_token` is then used in subsequent requests.

```shell
curl -s ${IDP_URL} \
-u "${OAUTH_ID}:${OAUTH_SECRET}" \
-d grant_type=password \
-d username="${OAUTH_USER}" \
-d password="${OAUTH_PWD}" \
-d scope="${SCOPE}" | \
jq -r '.access_token'
```

--------------------------------

### GraphQL Query for Employee Information

Source: https://fintlabs.github.io/api/graphql

This GraphQL query retrieves an employee's name, national identity number, positions, and place of employment given their employee ID. It requires a `String` variable for `ansattnummer`.

```graphql
query ($ansattnummer: String) {
  personalressurs(ansattnummer: $ansattnummer) {
    person {
      fodselsnummer {
        identifikatorverdi
      }
      navn {
        fornavn
        etternavn
      }
    }
    arbeidsforhold {
      ansettelsesprosent
      arbeidssted {
        organisasjonsKode {
          identifikatorverdi
        }
        organisasjonsnavn
      }
    }
  }
}
```

--------------------------------

### Cache Size for a Given Class

Source: https://fintlabs.github.io/api/overview

Returns the current size of the cache for a specified class. This endpoint helps in monitoring cache usage.

```APIDOC
## Size of cache for a given class

`/domain/package/class/cache/size`, i.e. `/administrasjon/personal/personalressurs/cache/size`

Return the size of the cache for a given class. The response looks like this:

```json
{
  "size": 10632
}
```

### Endpoint
`/domain/package/class/cache/size`

### Response
#### Success Response (200)
- **size** (integer) - The number of items currently in the cache for the specified class.
```

--------------------------------

### GraphQL Query for Class Membership

Source: https://fintlabs.github.io/api/graphql

This GraphQL query retrieves the names and contact information of all students within a specific teaching group, identified by its `systemId`. It requires a `String` variable for `systemId`.

```graphql
query ($systemId: String) {
  undervisningsgruppe(systemId: $systemId) {
    navn
    beskrivelse
    elevforhold {
      elev {
        kontaktinformasjon {
          mobiltelefonnummer
        }
        person {
          navn {
            fornavn
            etternavn
          }
        }
      }
    }
  }
}
```

--------------------------------

### Asynchronous Operations

Source: https://fintlabs.github.io/api/updating

FINT APIs use asynchronous operations for updates, allowing time for propagation through FINT components and adapters before backend processing.

```APIDOC
## Asynchronous Operations

FINT APIs handle updates asynchronously due to propagation delays. The process involves the client initiating an update, the FINT API responding with `202` and a `Location` header for status tracking, and the client polling the status resource until the operation completes.

### Process Flow

1.  **Client Initiates Update**: Sends a request to create, modify, or delete a resource.
2.  **FINT API Validation**: Validates syntax and responds with `202 Accepted` and a `Location` header pointing to a `/status/<uuid>` resource.
3.  **Client Fetches Status**: The client polls the `/status/<uuid>` resource.
    *   If pending, the FINT API responds with `202 Accepted`.
4.  **Operation Completion**: 
    *   **Success (Create/Update)**: `201 Created` with a `Location` header to the updated resource and the resource payload.
    *   **Success (Delete)**: `204 No Content`.
    *   **Backend Rejection**: `400 Bad Request` with an error message.
    *   **Conflict**: `409 Conflict` with the conflicting original information.
    *   **Temporary Failure**: `500 Internal Server Error` with an error message, allowing the client to retry.

The status resource is valid for 30 minutes.
```

--------------------------------

### Timestamp for Last Cache Update

Source: https://fintlabs.github.io/api/overview

Provides a timestamp indicating when the cache for a given class was last updated. Useful for determining data freshness.

```APIDOC
## Timestamp for when cache was last updated

`/domain/package/class/last-updated`, i.e. `/administrasjon/personal/personalressurs/last-updated`

Return a timestamp indicating when the cache was last updated. The response looks like this:

```json
{
  "lastUpdated": "1559551091034"
}
```

### Endpoint
`/domain/package/class/last-updated`

### Response
#### Success Response (200)
- **lastUpdated** (string) - A timestamp (in milliseconds since epoch) indicating when the cache was last updated.
```

--------------------------------

### Add Bearer Token to Request Header using curl

Source: https://fintlabs.github.io/api/accessing

This snippet shows how to include the obtained Bearer token in the `Authorization` header for making authenticated requests to FINT APIs. Replace `${TOKEN}` with the actual access token obtained previously and `https://.....` with the target API endpoint.

```shell
curl -H "Authorization: Bearer ${TOKEN}" https://.....
```

--------------------------------

### Health Check

Source: https://fintlabs.github.io/api/overview

Triggers a health check for the adapter providing data. The response indicates the connectivity and responsiveness of the adapter.

```APIDOC
## Health Check

`/domain/package/admin/health`, i.e. `/administrasjon/personal/admin/health`

Triggers a health check towards the adapter providing data. The response indicates whether the adapter is connected and responding.

### Endpoint
`/domain/package/admin/health`

### Example
`GET /administrasjon/personal/admin/health`

### Response
#### Success Response (200)
- **status** (string) - Indicates the health status (e.g., 'OK', 'ERROR').
- **message** (string) - A descriptive message about the health check result.
```

--------------------------------

### Deleting Objects

Source: https://fintlabs.github.io/api/updating

Delete objects using the DELETE method. Not all information classes support deletion.

```APIDOC
## Deleting Objects

### DELETE /domain/package/class/field/value

Use the DELETE method to remove objects. Note that deletion is not supported for all information classes.

### Method

DELETE

### Endpoint

`/domain/package/class/field/value`

*Example:* `/administrasjon/personal/fravar/systemid/abcdef1234`

### Parameters

#### Path Parameters

- **field** (string) - Required - The name of the identifiable field (e.g., `Identifikator`).
- **value** (string) - Required - The value of the identifiable field used to identify the resource.

### Response

#### Success Response (204)

- No Content: Indicates successful deletion.
```

--------------------------------

### Modifying Existing Objects

Source: https://fintlabs.github.io/api/updating

Modify existing objects using the PUT method, identifying the resource by its identifiable field and value.

```APIDOC
## Modifying Existing Objects

### PUT /domain/package/class/field/value

Use the PUT method to modify existing objects. The resource is identified by an identifiable field and its value.

### Method

PUT

### Endpoint

`/domain/package/class/field/value`

*Example:* `/administrasjon/personal/personalressurs/ansattnummer/123456`

### Parameters

#### Path Parameters

- **field** (string) - Required - The name of the identifiable field (e.g., `Identifikator`).
- **value** (string) - Required - The value of the identifiable field used to identify the resource.

### Request Body

- **resource** (object) - Required - The complete resource object reflecting the desired modifications. Attributes that can be modified are indicated in the information model.
```

--------------------------------

### Validate JSON Schema with Python

Source: https://fintlabs.github.io/api/tools

This Python script validates JSON data against a provided schema URI. It reads JSON data from standard input and uses the 'jsonschema' library for validation. It's designed to be piped with other tools like 'fint-curl'. Ensure you have the latest libraries from PyPI.

```python
#!/usr/bin/python

import jsonschema
import requests
import sys
import json
from tqdm import tqdm

r = requests.get(sys.argv[1])

schema = r.json()

data = json.load(sys.stdin)

validator = jsonschema.Draft7Validator(schema)

print "Validating", data["total_items"], "items..."

errors = 0

with open("errors.log", "a") as logfile:
	for item in tqdm(data["_embedded"]["_entries"]):
		try:
			validator.validate(item)
		except Exception as e:
			errors += 1
			print >> logfile, item
			print >> logfile, e
	
print "Validation completed with", errors, "errors."

```
Tokens:
Raw