openapi: 3.0.1
info:
  title: Asset Service API Specification
  description: The Asset REST Service provides API endpoints related to assets
  version: 1.1.0
servers:
- description: Generated server url
  url: https://api.btx.fr.banqup.com/core/asset
- description: Generated server url
  url: https://api.btx.eu.banqup.com/core/asset
paths:
  /v1/representations/{path}:
    get:
      tags:
      - Asset Representation
      summary: Retrieves the content of a representation or directory listing of representations
      operationId: retrieveRepresentation
      parameters:
      - name: path
        in: path
        description: The full path to a representation
        required: true
        schema:
          type: string
        example: subdir/invoice.en-US.txt
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '200':
          description: If 'path' refers to a representation, its content is returned.
            If 'path' refers to a directory, a listing of its contents is returned.
          content:
            application/octet-stream:
              schema:
                type: string
              example: |-
                This is the content of the file.
                It can be anything, like a text document or an image.
            application/json:
              schema:
                $ref: '#/components/schemas/DirectoryListing'
              example:
                representations:
                - invoice.en-US.html
                - invoice.nl-NL.html
                - invoice.nl-BE.html
                - subdir
        '400':
          description: Invalid Request Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
      security:
      - oauth2:
        - representation_read
      description: ' <br/> Scope: representation_read'
    put:
      tags:
      - Asset Representation
      summary: Upload or update a representation
      operationId: uploadRepresentation
      parameters:
      - name: path
        in: path
        description: The full path to a representation
        required: true
        schema:
          type: string
        example: subdir/invoice.en-US.txt
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              description: The content of the representation
        required: true
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '400':
          description: Invalid Request Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '200':
          description: Content of the representation
          content:
            application/octet-stream:
              schema:
                type: string
              example: |-
                This is the content of the file.
                It can be anything, like a text document or an image.
        '201':
          description: Content of the representation
          content:
            application/octet-stream:
              schema:
                type: string
              example: |-
                This is the content of the file.
                It can be anything, like a text document or an image.
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
      security:
      - oauth2:
        - representation_write
      description: ' <br/> Scope: representation_write'
    delete:
      tags:
      - Asset Representation
      summary: Deletes a representation
      operationId: deleteRepresentation
      parameters:
      - name: path
        in: path
        description: The full path to a representation
        required: true
        schema:
          type: string
        example: subdir/invoice.en-US.txt
      responses:
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '204':
          description: Deleted representation
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '400':
          description: Invalid Request Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
      security:
      - oauth2:
        - representation_write
      description: ' <br/> Scope: representation_write'
  /v1/assets/{asset}:
    get:
      tags:
      - Asset
      summary: Retrieve asset
      description: 'Retrieve asset <br/> Scope: asset_retrieve'
      operationId: retrieveAsset
      parameters:
      - name: Accept
        in: header
        description: Fallback content types for content negotiation
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - application/btx-pushnotification+json
        - application/json
      - name: Accept-Language
        in: header
        description: Fallback languages for language negotiation
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - en-GB
        - en
      - name: asset
        in: path
        description: Asset to retrieve
        required: true
        schema:
          type: string
        example: asset/iam/onboarding/template.en-US.pushnotification.json
      - name: type
        in: query
        description: Content type of the asset
        required: false
        schema:
          type: string
        example: application/btx-pushnotification+json
      - name: l
        in: query
        description: Language of the asset
        required: false
        schema:
          type: string
        example: en-GB
      responses:
        '200':
          description: Retrieved asset
          content:
            application/json:
              schema:
                type: string
              examples:
                json-asset-with-jsonata:
                  summary: JSON with JSONata placeholders
                  description: An example of a JSON asset that uses JSONata expressions
                    for dynamic content.
                  value:
                    notification:
                      title: data.matchInfo.homeTeam & ' vs. ' & data.matchInfo.awayTeam
                      body: data.matchInfo.status
                    data:
                      Nick: data.user.nickname
                      Room: data.matchInfo.homeTeam & 'VS' & data.matchInfo.awayTeam
                    option:
                      ttl: data.defaults.ttl
                      collapse: $collapseKey
                      priority: '$priorityOverride ? $priorityOverride : data.defaults.priority'
            text/html:
              schema:
                type: string
              examples:
                html-asset-with-freemarker:
                  summary: HTML with Freemarker placeholders
                  description: An example of an HTML asset that uses Freemarker templates
                    for dynamic content.
                  value: |
                    <!DOCTYPE html>
                    <html>
                    <head>
                      <title>${matchInfo.homeTeam} vs. ${matchInfo.awayTeam}</title>
                    </head>
                    <body>
                      <h1>Match Status: ${matchInfo.status}</h1>
                      <p>Hello, ${user.nickname}!</p>
                      <p>Welcome to the room for ${matchInfo.homeTeam}VS${matchInfo.awayTeam}.</p>
                    </body>
                    </html>
            text/plain:
              schema:
                type: string
              examples:
                text-asset-with-freemarker:
                  summary: Plain text with Freemarker placeholders
                  description: An example of a plain text asset that uses Freemarker
                    templates for dynamic content.
                  value: |
                    Match: ${matchInfo.homeTeam} vs. ${matchInfo.awayTeam}
                    Status: ${matchInfo.status}
                    User: ${user.nickname}
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '406':
          description: Not Acceptable Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
      security:
      - oauth2:
        - asset_retrieve
    post:
      tags:
      - Asset
      summary: Resolve asset
      description: 'Resolve asset <br/> Scope: asset_resolve'
      operationId: resolveAsset
      parameters:
      - name: Accept
        in: header
        description: Fallback content types for content negotiation
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - application/btx-pushnotification+json
        - application/json
      - name: Accept-Language
        in: header
        description: Fallback languages for language negotiation
        required: false
        schema:
          type: array
          items:
            type: string
        example:
        - en-GB
        - en
      - name: asset
        in: path
        description: Asset to resolve
        required: true
        schema:
          type: string
        example: asset/iam/onboarding/template.en-US.pushnotification.json
      - name: type
        in: query
        description: Content type of the asset
        required: false
        schema:
          type: string
        example: application/btx-pushnotification+json
      - name: l
        in: query
        description: Language of the asset
        required: false
        schema:
          type: string
        example: en-GB
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetInput'
        required: true
      responses:
        '401':
          description: Unauthorized Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 401
                error: UNAUTHENTICATED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Unauthorized
                detail: Access to the requested resource lacks valid authentication
                  credentials.
        '406':
          description: Not Acceptable Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 500
                error: INTERNAL
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Internal Server Error
                detail: The server encountered an unexpected error.
        '404':
          description: Not Found Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 404
                error: NOT_FOUND
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Not Found
                detail: The HTTP method was not allowed on this endpoint.
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 400
                error: BAD_REQUEST
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Bad Request
                detail: Bad Request message details.
        '200':
          description: Resolved asset
          content:
            application/json:
              schema:
                type: string
              examples:
                resolved-json-asset:
                  summary: Resolved JSON asset
                  description: An example of a JSON asset after its placeholders have
                    been resolved.
                  value:
                    notification:
                      title: Portugal vs. Denmark
                      body: great match!
                    data:
                      Nick: Mario
                      Room: PortugalVSDenmark
                    option:
                      ttl: 4800
                      priority: NORMAL
            text/html:
              schema:
                type: string
              examples:
                resolved-html-asset:
                  summary: Resolved HTML asset
                  description: An example of an HTML asset after its placeholders
                    have been resolved.
                  value: |
                    <!DOCTYPE html>
                    <html>
                    <head>
                      <title>Portugal vs. Denmark</title>
                    </head>
                    <body>
                      <h1>Match Status: great match!</h1>
                      <p>Hello, Mario!</p>
                      <p>Welcome to the room for PortugalVSDenmark.</p>
                    </body>
                    </html>
            text/plain:
              schema:
                type: string
              examples:
                resolved-text-asset:
                  summary: Resolved plain text asset
                  description: An example of a plain text asset after its placeholders
                    have been resolved.
                  value: |
                    Match: Portugal vs. Denmark
                    Status: great match!
                    User: Mario
        '403':
          description: Forbidden Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorProblemDetail'
              example:
                status: 403
                error: PERMISSION_DENIED
                requestId: a78150d2-7913-4ea6-933f-286cadac6745
                timestamp: 2018-08-27T12:34:50Z
                type: about:blank
                title: Forbidden
                detail: Access to the requested resource was denied.
      security:
      - oauth2:
        - asset_resolve
components:
  schemas:
    ApiErrorProblemDetail:
      required:
      - error
      - requestId
      - timestamp
      type: object
      properties:
        status:
          type: integer
          format: int32
        error:
          type: string
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        type:
          type: string
          format: uri
        title:
          type: string
        detail:
          type: string
        instance:
          type: string
          format: uri
        problems:
          type: array
          items:
            $ref: '#/components/schemas/NestedProblem'
        properties:
          type: object
          additionalProperties:
            type: object
    NestedProblem:
      required:
      - detail
      - error
      - title
      type: object
      properties:
        error:
          type: string
        title:
          type: string
        detail:
          type: string
        type:
          type: string
          format: uri
    AssetInput:
      type: object
      properties:
        recipient:
          $ref: '#/components/schemas/Recipient'
        data:
          type: object
          description: A flexible object to hold data specific to the asset being
            requested.
          example:
            matchInfo:
              homeTeam: Portugal
              awayTeam: Denmark
              status: great match!
            user:
              nickname: Mario
            defaults:
              ttl: 4800
              priority: NORMAL
      description: Input data for the asset
      example:
        recipient:
          id: 8c66dc06-424d-480e-a827-fb72101d9ea6
          firstName: Peter
          lastName: Smith
          language: en-GB
          email: peter.smith@example.com
          mobile: 447123456789
          brand: BTX
        data:
          matchInfo:
            homeTeam: Portugal
            awayTeam: Denmark
            status: great match!
          user:
            nickname: Mario
          defaults:
            ttl: 4800
            priority: NORMAL
    Recipient:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the recipient.
          example: 8c66dc06-424d-480e-a827-fb72101d9ea6
        firstName:
          type: string
          description: The recipient's first name.
          example: Peter
        lastName:
          type: string
          description: The recipient's last name.
          example: Smith
        language:
          type: string
          description: The preferred language of the recipient.
          example: en-GB
        email:
          type: string
          description: The recipient's email address.
          example: peter.smith@example.com
        mobile:
          type: string
          description: The recipient's mobile number.
          example: 447123456789
        brand:
          type: string
          description: The brand associated with the recipient.
          example: Banqup
      description: Represents the recipient of the asset.
      example:
        id: 8c66dc06-424d-480e-a827-fb72101d9ea6
        firstName: Peter
        lastName: Smith
        language: en-GB
        email: peter.smith@example.com
        mobile: 447123456789
        brand: BTX
    DirectoryListing:
      type: object
      properties:
        representations:
          type: array
          description: The representation's path.
          example: subdir/invoice.en-US.txt
          items:
            type: string
            description: The representation's path.
            example: subdir/invoice.en-US.txt
      description: A list of representations and subdirectories within this directory.
      example:
        representations:
        - invoice.en-US.html
        - invoice.nl-NL.html
        - invoice.nl-BE.html
        - subdir
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/client_credential/gettoken
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
        authorizationCode:
          authorizationUrl: https://api.btx.fr.banqup.com/oauth2/auth
          tokenUrl: https://api.btx.fr.banqup.com/oauth2/token
          scopes:
            info: Scopes are endpoint-specific, see each endpoint for required scope.
