openapi.yaml

openapi: 3.1.0
info:
  title: Europeana Media Proxy
  summary: thing
  description: |
    Micro-service for proxying Europeana `edm:isShownBy` and `edm:hasView` web
    resources from providers' websites.
  license:
    name: EUPL-1.2
    url: https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
  contact:
    url: https://github.com/europeana/media-proxy.js
  version: 0.2.6
externalDocs:
  description: Git repository README
  url: https://github.com/europeana/media-proxy.js#readme
tags:
  - name: media
    description: Media proxying
  - name: general
components:
  parameters:
    datasetId:
      name: datasetId
      in: path
      description: Dataset ID of item
      required: true
      schema:
        type: integer
      examples:
        oorlogsvlijt-example:
          summary: '"Oorlogsvlijt in Harderwijk." item dataset ID'
          value: 2020601
        maalaus-example:
          summary: '"maalaus" item (In Copyright) dataset ID'
          value: 2021009
    disposition:
      name: disposition
      in: query
      description: "Content disposition: either attachment (default) or inline"
      schema:
        type: string
    legacyRecordApiUrl:
      name: api_url
      in: query
      description: |
        Europeana Record API URL for web resource resolution & validation
        (from legacy media proxy URLs)
      schema:
        type: string
    legacyView:
      name: view
      in: query
      description: Web resource URL to proxy (from legacy media proxy URLs)
      schema:
        type: string
    localId:
      name: localId
      in: path
      description: Local ID of item
      required: true
      schema:
        type: string
      examples:
        oorlogsvlijt-example:
          summary: '"Oorlogsvlijt in Harderwijk." item local ID'
          value: https___1914_1918_europeana_eu_contributions_14524
        maalaus-example:
          summary: '"maalaus" item (In Copyright) local ID'
          value: _0CD7C92E0A18088F22111B9C00BD5EF1
    recordApiUrl:
      name: recordApiUrl
      in: query
      description: |
        Europeana Record API URL for web resource resolution & validation. If
        it does not end with /record, that will be appended.
      schema:
        type: string
    webResourceHash:
      name: webResourceHash
      in: path
      description: MD5 hash of web resource URL
      required: true
      schema:
        type: string
      examples:
        oorlogsvlijt-example:
          summary: '"Oorlogsvlijt in Harderwijk." item web resource hash'
          value: 304028f2553becc2bb0e4c0164439ec8
        maalaus-example:
          summary: '"maalaus" item (In Copyright) web resource hash'
          value: 8634fa12ac4d030a2a45b55b78ee5582
  responses:
    400BadRequest:
      description: |
        Proxying aborted, due to requested Record API being unsupported
      content:
        "*/*":
          schema:
            type: string
            example: Forbidden
paths:
  /:
    get:
      tags:
        - general
      summary: Root
      description: |
        Returns "OK". May be used as a health check by monitoring systems.
      operationId: getRootHealthCheck
      responses:
        "200":
          description: OK if app is healthy
          content:
            "*/*":
              schema:
                type: string
                example: OK
  "/media/{datasetId}/{localId}":
    parameters:
      - $ref: "#/components/parameters/datasetId"
      - $ref: "#/components/parameters/localId"
      - $ref: "#/components/parameters/recordApiUrl"
      - $ref: "#/components/parameters/disposition"
    get:
      tags:
        - media
      summary: Redirect to proxy media for edm:isShownBy
      description: >
        1. If a Record API URL has been specified in `recordApiUrl`, checks if
           it is supported as a data source, and if not, responds with status
           code 400. (If none specified, uses the default data source.)
        1. Looks in our database for a Europeana item identified by the path
           parameters `/{datasetId}/{localId}`. If no such item is found, responds
           with status code 404.
        1. Looks for a web resource associated with the item in its
           `edm:isShownBy`property. If no such web resource is found, responds
           with status code 404.
        1. Responds with status code 302 to redirect to the endpoint for proxying
           the media, by appending the MD5 hash of the web resource, i.e.
           `/media/{datasetId}/{localId}/{webResourceHash}`. Any parameters in the
           URL query will be preserved.
      operationId: getRedirectEdmIsShownBy
      responses:
        "302":
          description: Redirect
          headers:
            location:
              description: Europeana media proxy URL including MD5 hash of edm:isShownBy
              schema:
                type: string
                example: /media/2020601/https___1914_1918_europeana_eu_contributions_14524/304028f2553becc2bb0e4c0164439ec8
          content:
            "*/*":
              schema:
                type: string
                example: Found. Redirecting to
                  /media/2020601/https___1914_1918_europeana_eu_contributions_14524/304028f2553becc2bb0e4c0164439ec8
        "400":
          $ref: "#/components/responses/400BadRequest"
        "404":
          description: Item not found, or has no edm:isShownBy
          content:
            "*/*":
              schema:
                type: string
                example: Not Found
  "/media/{datasetId}/{localId}/{webResourceHash}":
    parameters:
      - $ref: "#/components/parameters/datasetId"
      - $ref: "#/components/parameters/localId"
      - $ref: "#/components/parameters/webResourceHash"
      - $ref: "#/components/parameters/recordApiUrl"
      - $ref: "#/components/parameters/disposition"
      - $ref: "#/components/headers/acceptAllHeader"
    get:
      tags:
        - media
      summary: Proxy media for specific web resource
      description: >
        1. If a Record API URL has been specified in `recordApiUrl`, checks if
           it is supported as a data source, and if not, responds with status
           code 400. (If none specified, uses the default data source.)
        1. Looks in our database for a Europeana item identified by the path
           parameters `/{datasetId}/{localId}`. If no such item is found, responds
           with status code 404.
        1. Looks for a web resource associated with the item in either its
           `edm:isShownBy` or `edm:hasView` properties, whose URL when MD5-hashed
           matches the path parameter `{webResourceHash}`. If no such web resource
           is found, responds with status code 404.
        1. Removes all but the following headers from the request before forwarding
           it to the provider's site:
           * `accept-encoding`
           * `accept-language`
           * `accept`
           * `if-match`
           * `if-modified-since`
           * `range`
           * `referer`
           * `user-agent`
        1. Starts proxying the web resource from the provider's site to the client.

        1. If the web resource is detected to be an HTML document, stops proxying
           and respond with status code 302 to redirect the client to the web page.
        1. If the web resource is any other media type, preserve only these upstream
           response headers, and remove the rest:
           * `accept-ranges`
           * `cache-control`
           * `content-encoding`
           * `content-length`
           * `content-range`
           * `content-type`
           * `etag`
           * `last-modified`
           * `link`
        1. If the upstream `content-type` header was omitted, default it to
           "application/octet-stream".
        1. Set the filename for the download (in the `content-disposition`
           response header) based on the format `Europeana.eu-{datasetId}-{localId}-{webResourceHash}.{extension}`.
           `{extension}` will be determined based on the `content-type` header
           or default to "bin" if unable to.
        1. Sets a custom response header `x-europeana-web-resource` containing
           the upstream URL of the proxied media.
        1. Respond with 200 status code.
      operationId: getProxyWebResource
      responses:
        "200":
          description: Media found and will be proxied
          headers:
            content-disposition:
              description: >
                Filename uses the format
                Europeana.eu-{datasetId}-{localId}-{webResourceHash}.{extension}
              schema:
                type: string
                example: attachment;
                  filename="Europeana.eu-2020601-https___1914_1918_europeana_eu_contributions_14524-304028f2553becc2bb0e4c0164439ec8.jpeg"
            x-europeana-web-resource:
              description: URL of proxied web resource
              schema:
                type: string
                example: https://europeana1914-1918.s3.amazonaws.com/attachments/152075/14524.152075.original.jpg
          content:
            "*/*":
              schema:
                type: string
                format: binary
        "302":
          description: Redirect to provider's site if requested media is HTML
          headers:
            location:
              description: Redirect URL for HTML resource
              schema:
                type: string
                example: https://www.example.org/
          content:
            "*/*":
              schema:
                type: string
                example: Found. Redirecting to
                  /media/2020601/https___1914_1918_europeana_eu_contributions_14524/304028f2553becc2bb0e4c0164439ec8
        "400":
          $ref: "#/components/responses/400BadRequest"
        "404":
          description: Item not found, or has no such web resource
          content:
            "*/*":
              schema:
                type: string
                example: Not Found
  "/{datasetId}/{localId}":
    parameters:
      - $ref: "#/components/parameters/datasetId"
      - $ref: "#/components/parameters/localId"
      - $ref: "#/components/parameters/legacyRecordApiUrl"
      - $ref: "#/components/parameters/legacyView"
      - $ref: "#/components/parameters/disposition"
    get:
      tags:
        - legacy
      summary: Redirect legacy media proxy URLs to current equivalents
      description: >
        Legacy media proxy URLs are of the format

        `/{datasetId}/{localId}?view={webResourceUrl}&apiUrl={recordApiUrl}`.


        1. The URL in `webResourceUrl` will be hashed to get `webResourceHash`

        1. The Record API URL in `apiUrl` will be moved to `recordApiUrl`

        1. Any other URL query parameters will be preserved

        1. The request will then be `301` redirected, e.g. to
           `/media/{datasetId}/{localId}/{webResourceHash}?recordApiUrl={recordApiUrl}`
      responses:
        "301":
          description: Redirect
          headers:
            location:
              description: Europeana media proxy URL /media prefix, and optionally MD5 hash of
                web resource
              schema:
                type: string
                example: /media/2020601/https___1914_1918_europeana_eu_contributions_14524
          content:
            "*/*":
              schema:
                type: string
                example: Found. Redirecting to
                  /media/2020601/https___1914_1918_europeana_eu_contributions_14524
servers:
  - url: https://proxy.europeana.eu
    description: Production server
  - url: https://media-proxy-js.test.eanadev.org
    description: Test server
  - url: http://localhost:3000
    description: Local development server