REST API streaming attachments
- Tor Oskar Ova Johnsen
- Øystein Thoen Sisjord
An earlier versjon of the Altinn REST API required the all forms, subforms and binary attachments to be included in a single POST with a max size limited to 50MB. Building permit applications often contain several large attachments. Including them in a single message is both cumbersome and the max limit could easily be reached. An improvement was added in Altinn version 17.1 (summer 2017) allowing attachments to be streamed and the complete message to be built in several steps.
Altinn documentation on streaming attachments is found here: https://altinn.github.io/docs/api/rest/meldinger/oppdatere/
General API documentation is also available here in English: https://www.altinn.no/api/Help
Example
We will show an example of sending a Rammesøknad with a Gjennomføringsplan as a subform and we will add a "Situasjonsplan" attachement. We will be representing a company with organization ID 910297937 for this example
| Step | Task | REST API |
|---|---|---|
| 1 | Initiate main form Rammesøknad with complete flag set to false. This starts a Altinn draft submission for the form. | |
| Response header from Altinn contains a "Location" field with the ID of the message. A message starting with the letter a (a5988855) indicates a draft message that can be altered. | Location: https://tt02.altinn.no/api/910297937/messages/a5988855 | |
| 2 | Initiate the Gjennomføringplan subform. A data section is added to the API message specifying that we are adding a "SubForm" and adding the XSD (data model) identifiers for Gjennomføringsplan V4. | |
The current state of the object can always be checked from Altinn. We can see that the second form has been added. | ||
| 3 | Add XML data to Gjennomføringplan | PUT: https://tt02.altinn.no/api/910297937/messages/a5988855/forms/3791204 Altinn response will be somewhat cryptic: Status Code: 204 No Content |
| 4 | Streaming an attachment It is important to URL-encode filenames since a valid filename can contain characters which are reserved in an URL. Example: situasjonsplan&fasade_tegning#3.pdf It is a valid filename, but will break an URL when trying to uploading the file. The reason for this is that both & and # have special meaings in an URL. More information on the subject: https://developers.google.com/maps/documentation/urls/url-encoding | After the upload, the message status has an added attachment: |
| 5 | Submitting the final package. When the main form, sub forms and attachments are ready for final submittal and signature in Altinn, with the flags "complete" and "sign" set to true. Request data payload contains the form ID in Altinn. | Remember that after final submittal, the ID number starting with an a (a5988855 in this case) will change to a different number starting with the letter b (b1234567). This is the final ID number for the signed form and is equal to the archive reference number in Altinn if the letter b is replaced with AR (AR1234567). |
Example code from the "DiBK Testmotor" can be found here:
These two videos show how to run this sequence in the test engine and how to check the status of the submission from the Status API: