Overview

This should give you a high level view of the terminology we use.

The manifest

A manifest is a declaration of what your adapter can do and what state it has. The terminology was originally inspired by Mozillas WoT RFC (although the rfc has evolved quite a bit since). The basic idea is that your adapter contains any number of things that can perform various actions.

If you have used Prometheus then this should feel somewhat familiar. Our backend will periodically scrape your adapter for its manifest. This doubles as a health check as we can use scraping errors to trigger alerting.

Things

Things can physical things like doors or lamps, but they can also represent more abstract things like apis for access control. A thing in our model can have state and actions. State can be used for things like triggering alerts if a door is left unlocked at certain times of the day. An action represents something your adapter can do and is what will be triggered when a user triggers something in Oslonøkkelen.

Actions

An action represents what the adapter can do. This can be everything from opening a door to invoking a remote api to provide access control. Further down you can read more about action requests and responses.

Operations, things and actions

Users of Oslonøkkelen can execute operations. Each operation is mapped to a chain of actions. The chain can consist of one or more actions executed sequentially. A single failing action will break the entire chain. Actions are allowed to deny requests making it possible to use actions to provide authorization for other actions.

High level architecture

When someone has developed a new adapter and registered it with Oslonøkkelen a periodical manifest scraping job will start. Actions found in the manifest can be mapped to operations visisible to users of Oslonøkkelen. Each time someone executes an operation in Oslonøkkelen our backend will create a chain of the relevant actions and invoke the adapters in sequence.

Action request and response

When a user triggers an operation in the app one or more actions will be executed in a chain. The job of the adapter is to take the request, process it and produce a response indicating how it went. If one action results in an error or denied response the chain will be broken and no further actions executed.

The action request

A request consists of the following fields.

Field Description

Field	Description
Request id	Each request has an id that can be used for tracing / correlating errors.
Thing + action id	Identifies the target action.
Attachments	Any number of attachments. See table below for a list of possible request attachments.
Time budget	The app will use a time out if no response is received within x seconds after the user triggered an operation. Each action request will contain an estimated time budget the adapter should strive to respond within. Returning a `temporary error` within the allocated time is so much better than not returning at all leaving backend to wonder if your adapter is alive and processing requests.

Request id

Each request has an id that can be used for tracing / correlating errors.

Thing + action id

Identifies the target action.

Attachments

Any number of attachments. See table below for a list of possible request attachments.

Time budget

The app will use a time out if no response is received within x seconds after the user triggered an operation. Each action request will contain an estimated time budget the adapter should strive to respond within.

Returning a temporary error within the allocated time is so much better than not returning at all leaving backend to wonder if your adapter is alive and processing requests.

The response

A response consists of the following fields.

Field	Description
Status	Each response must have one of the following status codes. Success All good Access denied: Adapter refused access Trying again will probably produce the same result Temporary error: Temporary errors like network timeouts etc Trying again in a few seconds might work Permanent error: Unexpected technical errors These errors will probably trigger alerting Trying the same request again is likely to produce the same result
Attachments	Any number of attachments. See table below for a list of possible response attachments.

Field

Description

Status

Each response must have one of the following status codes.

Success
- All good
Access denied:
- Adapter refused access
- Trying again will probably produce the same result
Temporary error:
- Temporary errors like network timeouts etc
- Trying again in a few seconds might work
Permanent error:
- Unexpected technical errors
- These errors will probably trigger alerting
- Trying the same request again is likely to produce the same result

Attachments

Any number of attachments. See table below for a list of possible response attachments.

Attachments

We support various attachments on both the request and response. The manifest can declare required request attachments. This is particularly useful for actions that work as access control as they have to know something about the end user. Such actions can declare in their manifest that they require various user data (remember gdpr).

Attachment Description Request Response

Attachment	Description	Request	Response
Fødselsnummer	Gives the adapter access to the users fødselsnummer. Intended for Oslo kommunes services like Gjenbruksid.
Code	Some adapters might produce various codes. These codes can be rendered as QR or bar-codes on the users device.
Punch card	Used to indicate how much of a limited resource is left. "You have used x of y visits".
End user message	Format a message that will be displayed to the end user. Can be very useful for explaining errors.
Error description	Technical error description. Can contain a `code` and a technical debug message. The code can be used for mapping error codes to human-readable messages.

Fødselsnummer

Gives the adapter access to the users fødselsnummer. Intended for Oslo kommunes services like Gjenbruksid.

Code

Some adapters might produce various codes. These codes can be rendered as QR or bar-codes on the users device.

Punch card

Used to indicate how much of a limited resource is left. "You have used x of y visits".

End user message

Format a message that will be displayed to the end user. Can be very useful for explaining errors.

Error description

Technical error description. Can contain a code and a technical debug message. The code can be used for mapping error codes to human-readable messages.