openapi: 3.0.1
info:
  title: uppladdningstjänst, geodatakatalog
  version: 1.0.0
  description: |-
    Här beskrivs API:et för uppladdning av filer till geodatakatalogen via uppladdningstjänsten.

    Uppladdning görs i två steg:
      1. Skapa resurs.
      2. Uppladdning av fil till skapad resurs eller registrering av eftersändning.

    En fil kan tas bort om behov finns via API:et, men det finns inget krav att städa bort gamla filer efter sig.
    Filer kan rensas automatiskt om de inte refereras till i något domänobjekt.

    Det går bara att administrera resurser som man själv har skapat.
  contact:
    name: Lantmäteriet
    url: 'https://www.lantmateriet.se'
servers:
  - url: 'https://api.lantmateriet.se/distribution/geodatakatalog/uppladdning/v1'
    description: Produktion
  - url: 'https://api-ver.lantmateriet.se/distribution/geodatakatalog/uppladdning/v1'
    description: Verifikation
paths:
  /resurs:
    post:
      summary: Skapa resurs
      description: För att ladda upp en fil eller registrera en eftersändning måste en resurs först skapas.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/skaparesurs'
            example:
              informationstyp: "detaljplan"
      responses:
        '201':
          $ref: '#/components/responses/NyResurs'
        '400':
          $ref: '#/components/responses/Fel400'
        '403':
          $ref: '#/components/responses/Fel403'
        '500':
          $ref: '#/components/responses/Fel500'
        default:
          $ref: '#/components/responses/Fel'
  /resurs/{referensidentitet}:
    get:
      summary: Hämta resursinformation
      description: Hämta information om en resurs. Endast den som skapat resursen kan hämta dess information.
      parameters:
        - $ref: '#/components/parameters/referensidentitet'
      responses:
        '200':
          $ref: '#/components/responses/Resurs'
        '400':
          $ref: '#/components/responses/Fel400'
        '403':
          $ref: '#/components/responses/Fel403'
        '404':
          $ref: '#/components/responses/Fel404'
        '500':
          $ref: '#/components/responses/Fel500'
        default:
          $ref: '#/components/responses/Fel'
    delete:
      summary: Ta bort resurs
      description: >-
        Ta bort alla filer (revisioner) som finns på resursen. Filerna tas bort, men resursen finns kvar.
        En ny uppladdning kan göras vid ett senare tillfälle. Endast den som skapat resursen kan ta bort den.
      parameters:
        - $ref: '#/components/parameters/referensidentitet'
      responses:
        '204':
          description: Lyckad borttagning resursen.
        '400':
          $ref: '#/components/responses/Fel400'
        '403':
          $ref: '#/components/responses/Fel403'
        '404':
          $ref: '#/components/responses/Fel404'
        '500':
          $ref: '#/components/responses/Fel500'
        default:
          $ref: '#/components/responses/Fel'
  /resurs/{referensidentitet}/leverans:
    post:
      summary: Ladda upp fil
      description: >-
        Ladda upp fil till en resurs. En eftersändning registreras automatiskt.
        Flera uppladdningar till samma resurs är tillåten. T.ex. om filen ska uppdateras.
        Vid varje ny uppladdning skapas en ny revision. Endast den som skapat resursen kan ladda upp filer till den.
      parameters:
        - $ref: '#/components/parameters/referensidentitet'
        - in: header
          name: Content-Disposition
          description: >-
            Filens namn `attachment; filename="namn.fil"`. Vid konsumtion skickas detta filnamn till klienten.
          required: true
          schema:
            type: string
        - in: header
          name: Content-Type
          description: Filens mediatyp. Vid konsumtion skickas denna mediatyp till klienten.
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        '200':
          $ref: '#/components/responses/Resurs'
        '400':
          $ref: '#/components/responses/Fel400'
        '403':
          $ref: '#/components/responses/Fel403'
        '404':
          $ref: '#/components/responses/Fel404'
        '413':
          $ref: '#/components/responses/Fel413'
        '500':
          $ref: '#/components/responses/Fel500'
        default:
          $ref: '#/components/responses/Fel'
  /resurs/{referensidentitet}/eftersandning:
    post:
      summary: Registrera eftersändning
      description: >-
        Registrera en eftersändning (redirect) till en resurs på Internet.
        Flera registreringar är tillåten. T.ex. om URL:en måste uppdateras.
        Vid varje ny registrering skapas en ny revision.
        Endast den som skapat resursen kan registrera en eftersändning på den. Endast https-länkar tillåts.
      parameters:
        - $ref: '#/components/parameters/referensidentitet'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/eftersandning'
            example:
              href: 'https://valfri.url/till/en/fil'
      responses:
        '200':
          $ref: '#/components/responses/Resurs'
        '400':
          $ref: '#/components/responses/Fel400'
        '403':
          $ref: '#/components/responses/Fel403'
        '404':
          $ref: '#/components/responses/Fel404'
        '500':
          $ref: '#/components/responses/Fel500'
        default:
          $ref: '#/components/responses/Fel'
components:
  parameters:
    referensidentitet:
      description: Resursens id
      name: referensidentitet
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    skaparesurs:
      type: object
      properties:
        informationstyp:
          description: Domäntillhörighet, t.ex "detaljplan"
          type: string
      required:
        - informationstyp
    resurs:
      type: object
      properties:
        informationstyp:
          description: Domäntillhörighet
          type: string
        referensidentitet:
          description: >-
            Unik identifierare för resursen. Används både vid uppladdning och nedladdning.
            Identifieraren är stabil och kan användas för att referera till dokument från domänobjektet.
          type: string
          format: uuid
        revision:
          description: Resursens revision. När resursen uppdateras skapas en ny revision.
          type: integer
          minimum: 1
      required:
        - informationstyp
        - referensidentitet
    eftersandning:
      type: object
      properties:
        href:
          description: URL där filen kan laddas ner. Måste vara av typen https.
          type: string
          format: uri
      required:
        - href
  responses:
    NyResurs:
      description: En ny resurs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/resurs'
          example:
            informationstyp: 'detaljplan'
            referensidentitet: '7ef18284-236d-46ae-9988-c2ad4ef957b7'
    Resurs:
      description: Den befintliga resursen.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/resurs'
          example:
            informationstyp: 'detaljplan'
            referensidentitet: '7ef18284-236d-46ae-9988-c2ad4ef957b7'
            revision: 1
    Fel400:
      description: Felaktigt anrop
      content:
        application/json:
          schema:
            $ref: 'http://namespace.lantmateriet.se/distribution/produkter/fault/v1/fault-1.0.json'
          example:
            code: 400
            reason: 'Bad request'
            errors:
              - 'Felaktigt anrop'
    Fel403:
      description: Förbjudet anrop
      content:
        application/json:
          schema:
            $ref: 'http://namespace.lantmateriet.se/distribution/produkter/fault/v1/fault-1.0.json'
          example:
            code: 403
            reason: 'Forbidden'
            errors:
              - 'Åtkomst nekas'
    Fel404:
      description: Resursen finns inte
      content:
        application/json:
          schema:
            $ref: 'http://namespace.lantmateriet.se/distribution/produkter/fault/v1/fault-1.0.json'
          example:
            code: 404
            reason: 'Not Found'
            errors:
              - 'Resursen finns inte'
    Fel413:
      description: Anropet innehåller för mycket data
      content:
        application/json:
          schema:
            $ref: 'http://namespace.lantmateriet.se/distribution/produkter/fault/v1/fault-1.0.json'
          example:
            code: 413
            reason: 'Payload to large'
            errors:
              - 'Anropet innehåller för mycket data'
    Fel500:
      description: Internt fel i tjänsten
      content:
        application/json:
          schema:
            $ref: 'http://namespace.lantmateriet.se/distribution/produkter/fault/v1/fault-1.0.json'
          example:
            code: 500
            reason: 'Internal server error'
            errors:
              - 'Internt fel'
    Fel:
      description: Övriga fel
      content:
        '*/*':
          schema:
            type: string