Create a API design for the generic order endpoint

[SandGrainOne]

Description

We need to define the model for a notifications order that is more agnistic to channel choices. It must be possible to ask for email, sms, sms preferred and email preferred. The order needs to be able to take in texts for both type of channels.

Specification

openapi: 3.0.1
info:
  title: Altinn.Notifications
  version: '1.0'
paths:
  /notifications/api/v1/orders:
    post: 
      tags: 
        - Orders
      summary: Endpoint for posting a notification order    
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationOrderRequestExt'
      responses:
        '202':
          description: The notification order request was accepted
          headers:
            Location:
              description: Link to access the newly created notification order.
              schema:
                type: string
                description: Link to access the newly created notification order.
                format: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationOrderRequestResponseExt'
        '400':
          description: The notification order request is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '401':
          description: Caller is unauthorized
        '403':
          description: Caller is not authorized to access the requested resource
components:
  schemas:
    NotificationOrderRequestExt:
      type: object
      properties:
        requestedSendTime:
          type: string
          description: Gets or sets the send time of the email. Defaults to UtcNow
          format: date-time
        sendersReference:
          type: string
          description: Gets or sets the senders reference on the notification
          nullable: true
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/RecipientExt'
          description: Gets or sets the list of recipients
        ignoreReservation:
          type: boolean
          description: >-
            Gets or sets whether notifications generated by this order should ignore KRR reservations
          nullable: true
        resourceId:
          type: string
          description: >-
            Gets or sets the id of the resource that the notification is related
            to
          nullable: true
        conditionEndpoint:
          type: string
          description: Gets or sets the condition endpoint used to check the send condition
          format: uri
          nullable: true
        notificationChannel:
          $ref: '#/components/schemas/NotificationChannelExt'          
        emailTemplate:
          $ref: '#/components/schemas/EmailTemplateExt'
        smsTemplate:
          $ref: '#/components/schemas/SmsTemplateExt'        
      additionalProperties: false
      description: Class representing an email notiication order request
    EmailContentTypeExt:
      enum:
        - Plain
        - Html
      type: string
      description: Enum describing available content types for an email.
    EmailTemplateExt:
      type: object
      properties:
        fromAddress:
          type: string
          description: Gets the from adress of emails created by the template
          nullable: true
        subject:
          type: string
          description: Gets the subject of emails created by the template
          nullable: true
        body:
          type: string
          description: Gets the body of emails created by the template
          nullable: true
        contentType:
          $ref: '#/components/schemas/EmailContentTypeExt'
      additionalProperties: false
      description: Template for an email notification
    NotificationChannelExt:
      enum:
        - Email
        - Sms
        - EmailPreferred
        - SmsPreferred
      type: string
      description: Enum describing available notification channels.
    NotificationOrderRequestResponseExt:
      type: object
      properties:
        orderId:
          type: string
          description: The order id
          format: uuid
          nullable: true
        recipientLookup:
          $ref: '#/components/schemas/RecipientLookupResultExt'
      additionalProperties: false
      description: A class representing a container for an order id.
    RecipientExt:
      type: object
      properties:
        emailAddress:
          type: string
          description: Gets or sets the email address of the recipient
          nullable: true
        mobileNumber:
          type: string
          description: Gets or sets the mobile number of the recipient
          nullable: true
        organizationNumber:
          type: string
          description: Gets or sets the organization number of the recipient
          nullable: true
        nationalIdentityNumber:
          type: string
          description: Gets or sets the national identity number of the recipient
          nullable: true
        isReserved:
          type: boolean
          description: >-
            Gets or sets a value indicating whether the recipient is reserved
            from digital communication
          nullable: true
      additionalProperties: false
      description: Class representing a notification recipient
    RecipientLookupResultExt:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/RecipientLookupStatusExt'
        isReserved:
          type: array
          items:
            type: string
          description: List of id numbers for the recipients that are reserved
          nullable: true
        missingContact:
          type: array
          items:
            type: string
          description: >-
            List of id numbers for the recipients where no contact points were
            identified
          nullable: true
      additionalProperties: false
      description: Class describing a summary of recipient lookup for a notification order
    RecipientLookupStatusExt:
      enum:
        - Success
        - PartialSuccess
        - Failed
      type: string
      description: Enum describing the success rate for recipient lookup
    SmsTemplateExt:
      type: object
      properties:
        senderNumber:
          type: string
          description: Gets the number from which the SMS is created by the template
          nullable: true
        body:
          type: string
          description: Gets the body of SMSs created by the template
          nullable: true
      additionalProperties: false
      description: Template for an sms notification
    ValidationProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          nullable: true
      additionalProperties: {}
tags:
  - name: SendCondition
    description: Private API

Tasks

• [x] Create an OpenAPI specification suggestion for the model and endpoint
• [x] Share the specification with possible consumers of the API. Like SKD, as input to the pilot. Final specification can be added as a comment to this issue.

Acceptance criteria

• [x] Completed OpenAPI specification

[olebhansen]

API shared - pending feedback and/or additional distribution/people to share it with. Will keep task open through the sprint.