api_services_app_backend.yaml

openapi: 3.0.3
servers:
  - url: https://api-app.io.pagopa.it/api/v2
info:
  title: Services App Backend API
  version: 13.34.3
tags:
  - name: search
    description: Search APIs
  - name: details
    description: Retrieve resources details
  - name: featured
    description: Retrieve featured Lists
security:
  - Bearer: []
paths:
  /institutions:
    get:
      tags:
        - search
      summary: Find institutions
      description: Multiple status values can be provided with comma separated strings
      operationId: findInstitutions
      parameters:
        - name: search
          in: query
          description: A full-text search query expression
          required: false
          schema:
            type: string
        - name: scope
          in: query
          description: Institution scope
          required: false
          schema:
            $ref: '#/components/schemas/ScopeType'
        - name: limit
          in: query
          description: >-
            The number of search results to retrieve. This can be used in
            conjunction with skip to implement client-side paging of search
            results
            (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionstopandskip).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: >-
            The number of search results to skip
            (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionstopandskip).
            This value cannot be greater than 100,000.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionsResource'
        '400':
          description: Bad Request
        '401':
          description: Bearer token null or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
  /institutions/featured:
    get:
      tags:
        - featured
      summary: Retrieve featured intitutions
      operationId: getFeaturedInstitutions
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Institutions'
        '401':
          description: Bearer token null or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
  /institutions/{institutionId}/services:
    get:
      tags:
        - search
      summary: Find services for institution
      description: Given an Institution allow to find its services
      operationId: findInstutionServices
      parameters:
        - name: institutionId
          in: path
          description: ID of the institution to search for services
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: >-
            The number of search results to retrieve. This can be used in
            conjunction with skip to implement client-side paging of search
            results
            (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionstopandskip).
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: >-
            The number of search results to skip
            (https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_SystemQueryOptionstopandskip).
            This value cannot be greater than 100,000.
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 100
            default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionServicesResource'
        '400':
          description: Bad Request
        '401':
          description: Bearer token null or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
  /services/featured:
    get:
      tags:
        - featured
      summary: Retrieve featured services
      operationId: getFeaturedServices
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturedServices'
        '401':
          description: Bearer token null or expired
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
  /services/{serviceId}:
    get:
      tags:
        - details
      summary: Retrieve service details
      description: Retrieve a service by ID
      operationId: getServiceById
      parameters:
        - name: serviceId
          in: path
          description: ID of service to return
          required: true
          schema:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDetails'
        '401':
          description: Bearer token null or expired
        '404':
          description: Not found
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemJson'
        '502':
          description: Bad gateway
        '504':
          description: Gateway timeout
components:
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
  schemas:
    InstitutionsResource:
      allOf:
        - $ref: '#/components/schemas/Institutions'
        - $ref: '#/components/schemas/PaginationResultSet'
    Institutions:
      type: object
      properties:
        institutions:
          type: array
          items:
            $ref: '#/components/schemas/Institution'
      required:
        - institutions
    Institution:
      type: object
      properties:
        id:
          type: string
          description: Institution ID
        name:
          type: string
          description: Institution Name
        fiscal_code:
          $ref: '#/components/schemas/OrganizationFiscalCode'
      required:
        - id
        - name
        - fiscal_code
    InstitutionServicesResource:
      allOf:
        - $ref: '#/components/schemas/Services'
        - $ref: '#/components/schemas/PaginationResultSet'
    Services:
      type: object
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceMinified'
      required:
        - services
    ServiceMinified:
      type: object
      description: Service data (minified)
      properties:
        id:
          type: string
          description: Service ID
        name:
          type: string
          description: Service Name
          example: Tari
        version:
          type: integer
          description: Service Version
      required:
        - id
        - name
        - version
    ServiceDetails:
      type: object
      properties:
        id:
          type: string
          description: Service ID
        name:
          type: string
          description: Service name
        description:
          type: string
          description: Service description
        organization:
          $ref: '#/components/schemas/Organization'
        available_notification_channels:
          $ref: '#/components/schemas/AvailableNotificationChannels'
        metadata:
          $ref: '#/components/schemas/ServiceMetadata'
        version:
          type: integer
          description: Service version
      required:
        - id
        - name
        - version
        - organization
        - metadata
    FeaturedServices:
      type: object
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/FeaturedService'
      required:
        - services
    FeaturedService:
      allOf:
        - $ref: '#/components/schemas/ServiceMinified'
        - type: object
          properties:
            organization_name:
              type: string
              description: Organization Name
    ServiceMetadata:
      description: A set of service metadata properties
      allOf:
        - $ref: '#/components/schemas/ServiceBaseMetadata'
        - type: object
          properties:
            topic:
              $ref: '#/components/schemas/ServiceTopic'
    ServiceTopic:
      type: object
      properties:
        id:
          type: number
          description: The topic id
          example: 3
        name:
          type: string
          description: The topic name
          example: Benessere sociale
      required:
        - id
        - name
    ServiceBaseMetadata:
      type: object
      description: A set of common service metadata properties
      properties:
        web_url:
          type: string
          minLength: 1
        app_ios:
          type: string
          minLength: 1
        app_android:
          type: string
          minLength: 1
        tos_url:
          type: string
          minLength: 1
        privacy_url:
          type: string
          minLength: 1
        address:
          type: string
          minLength: 1
        phone:
          type: string
          minLength: 1
        email:
          type: string
          minLength: 1
        pec:
          type: string
          minLength: 1
        cta:
          type: string
          minLength: 1
        token_name:
          type: string
          minLength: 1
        support_url:
          type: string
          minLength: 1
        category:
          type: string
          enum:
            - SPECIAL
            - STANDARD
        custom_special_flow:
          type: string
          minLength: 1
        scope:
          type: string
          enum:
            - NATIONAL
            - LOCAL
      required:
        - scope
    Organization:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        fiscal_code:
          type: string
          description: Organization's fiscal code.
          pattern: ^[0-9]{11}$
          example: 12345678901
        department_name:
          type: string
          minLength: 1
      required:
        - name
        - fiscal_code
    OrganizationFiscalCode:
      type: string
      x-import: '@pagopa/ts-commons/lib/strings'
      format: OrganizationFiscalCode
    PaginationResultSet:
      type: object
      properties:
        offset:
          type: number
          description: result set offset
        limit:
          type: number
          description: result set size
        count:
          type: number
          description: total record count
      required:
        - offset
        - limit
        - count
    AvailableNotificationChannels:
      description: All the notification channels available for a service
      type: array
      items:
        $ref: '#/components/schemas/NotificationChannel'
    NotificationChannel:
      type: string
      description: All notification channels
      enum:
        - EMAIL
        - WEBHOOK
      example:
        - EMAIL
    ScopeType:
      type: string
      description: Institutions/Services Scopes
      enum:
        - NATIONAL
        - LOCAL
    ProblemJson:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: |-
            An absolute URI that identifies the problem type. When dereferenced,
            it SHOULD provide human-readable documentation for the problem type
            (e.g., using HTML).
          default: about:blank
          example: https://example.com/problem/constraint-violation
        title:
          type: string
          description: >-
            A short, summary of the problem type. Written in english and
            readable

            for engineers (usually not suited for non technical stakeholders and

            not localized); example: Service Unavailable
        status:
          type: integer
          format: int32
          description: >-
            The HTTP status code generated by the origin server for this
            occurrence

            of the problem.
          minimum: 100
          maximum: 600
          exclusiveMaximum: true
          example: 200
        detail:
          type: string
          description: |-
            A human readable explanation specific to this occurrence of the
            problem.
          example: There was an error processing the request
        instance:
          type: string
          format: uri
          description: >-
            An absolute URI that identifies the specific occurrence of the
            problem.

            It may or may not yield further information if dereferenced.