openapi: 3.0.1
info:
  title: Partner Resources REST Provider
  description: |-
    This document defines the Partner Resources REST Provider, which should be implemented as a REST endpoint to expose a partner’s resources to the Duda platform.

    **The Configuration of partner REST Resource Provider inside the Duda Platform contains the following fields:**
    * **Endpoint base url (base_url)**
        * The base url of the REST endpoint where the Partner Resources REST Provider is implemented (must start with ***https://***).
        The Duda platform must be able to reach this url.
    * **Authorization Header Value (auth_header_value)**
        * An optional token value that will be included in the HTTP `<auth_header_name>` header of every REST request.
        This value is stored securely in the Duda platform and is provided by the partner.
    * **Authorization Header Name (auth_header_name)**
        * An optional authorization header name that will be included as the header of every REST request with <auth_header_value>.
        The default is `Authorization`.

    Every REST request will be sent to `base url + method path` with `auth_header_name` header holding `auth_header_value`, i.e.:
    ```
    curl -X GET -H "auth_header_name: auth_header_value" <base_url>/method_path
    ```

    **Standard Interaction Flow of Duda platform with Partner Resources REST Provider (example for Image resource):**
    1. ***Provider Initialization***:
        * Duda sends a `GET /info` request to retrieve a list of the supported resource types and search capabilities of the provider.
    2. ***User Opens Media Manager***
        * Duda sends a `GET /search/images?page=1&per_page=<n>` request (with no query parameter) to fetch the default set of images.
    3. ***User Searches in the Media Manager for images with a specific query***
        * Duda sends a `GET /search/images?query=<query>&page=1&per_page=<n>` request to retrieve images that match the user’s search query.
    4. ***User Scrolls in the Media Manager to fetch more images***
        * Duda sends a `GET /search/images?query=<query>&page=2&per_page=<n>` request to load the next page of results for the same query.
    5. ***User decides to use Image and adds it to a Site***
        * Duda sends a `GET /images/<id>` request to fetch detailed information about the selected image.
        * The image is then downloaded, stored in Duda’s site resource storage and further optimized.


    **Additional NOTES:**
    * **Search Results Ordering**

        Resources returned by the partner REST implementation will always appear <b>before</b> those from other resource providers
        integrated by Duda (e.g., Pexels, Giphy) in the Media Picker..
    * **Exception Handling**:
      * Errors during REST invocation will be logged by Duda for troubleshooting.
      * From the user's Media Picker experience:
        * Error during resource search:

            If an error occurs, the results from the partner REST implementation will not be displayed. However,
            results from other providers will still appear, and no error message will be shown to the user.
        * Error during resource addition:

            If an error occurs when adding a partner REST resource to the site, the user will be notified that the operation has failed.
    * **API Evolution**:

        As the API evolves, new resource types, search capabilities, and data structures may be introduced as optional features.
        This ensures backward compatibility with existing functionality.
  version: "1.1"
paths:
  /images/{id}:
    get:
      tags:
      - images
      summary: Get `ImageResource` by id
      description: "Should return `ImageResource` by id returned from image search.\
        \ This endpoint is triggered when a user proactively adds an image to be used\
        \ in the site from the Media Manager. Once the endpoint returns a valid `ImageResource`,\
        \ the Duda system initiates the import of the image into Duda. Duda downloads\
        \ the image using the `ImageUrls.original` url to the site's storage and performs\
        \ further image optimizations."
      operationId: getImage
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageResource"
  /info:
    get:
      tags:
      - info
      summary: Get details and search capabilities of resource provider
      operationId: getResourceProviderInfo
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceProviderInfo"
  /search/images:
    get:
      tags:
      - images
      summary: 'Search images by declared search capabilities. '
      description: "Should return `ImageSearchResult` containing list of `ImageResource`\
        \ with `id`, that can be used in `/images/{id}` operation. In case when only\
        \ pagination parameters are passed without any search criteria, the provider\
        \ should return the \"default\" images. The `ImageResource` should contain\
        \ the `ImageUrls` field. Duda platform will be using ImageUrls.preview and\
        \ ImageUrls.small urls to show user the image as part of search results."
      operationId: searchImages
      parameters:
      - name: query
        in: query
        description: search query
        schema:
          type: string
      - name: page
        in: query
        description: page number (starts with 1)
        required: true
        schema:
          type: integer
          format: int32
      - name: per_page
        in: query
        description: number of results per page
        required: true
        schema:
          type: integer
          format: int32
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageSearchResult"
components:
  schemas:
    ImageResource:
      required:
      - id
      - name
      - urls
      type: object
      properties:
        id:
          type: string
        name:
          type: string
          description: Image file name with extension representing image type (i.e.
            "big-smile.jpg")
        urls:
          $ref: "#/components/schemas/ImageUrls"
    ImageSearchResult:
      type: object
      properties:
        images:
          type: array
          items:
            $ref: "#/components/schemas/ImageResource"
        page:
          type: integer
          format: int32
        per_page:
          type: integer
          format: int32
        total_results:
          type: integer
          format: int32
    ImageUrls:
      required:
      - original
      type: object
      properties:
        original:
          type: string
          description: "Url to the original image, used for downloading the image\
            \ to the site's storage"
        preview:
          type: string
          description: "Optional url to the image preview in big size, used for showing\
            \ the image in the search results"
        small:
          type: string
          description: "Optional url to the image preview in small size, used for\
            \ showing the image in the search results"
      description: Image urls for different sizes
    ProviderDetails:
      type: object
      properties:
        link:
          type: string
        logo:
          type: string
        name:
          type: string
    ResourceProviderInfo:
      required:
      - search_capabilities
      type: object
      properties:
        provider_details:
          $ref: "#/components/schemas/ProviderDetails"
        search_capabilities:
          $ref: "#/components/schemas/SearchCapabilities"
    SearchCapabilities:
      type: object
      properties:
        resource_types:
          type: array
          items:
            type: string
            description: "Type of the resource supported by the provider. As of now\
              \ only IMAGE is supported. In the future, VIDEO will be added."
            enum:
            - IMAGE
        search_images_capabilities:
          type: array
          items:
            type: string
            enum:
            - BY_QUERY
  securitySchemes:
    token:
      type: http
      scheme: bearer
