openapi3.yaml

openapi: 3.0.1
info:
  title: mapproxy-api
  description: rest api service to manage layers in mapproxy
  version: 1.15.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
security: []
paths:
  /config:
    get:
      operationId: getConfig
      tags:
        - Config
      summary: get current mapproxy config
      responses:
        '200':
          description: OK
          content:
            application/yaml:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/getConfigResponse'
                  - $ref: '#/components/schemas/getConfigYamlResponse'
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/getConfigResponse'
                  - $ref: '#/components/schemas/getConfigYamlResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Ineternal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /layer:
    post:
      operationId: addLayer
      tags:
        - Layer
      summary: add layer to mapproxy
      responses:
        '201':
          description: Created
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Ineternal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/layer'
    delete:
      operationId: removeLayer
      tags:
        - Layer
      summary: remove layer from mapproxy
      parameters:
        - name: layerNames
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/failedRemoveDiscreteLayers'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                LayerNotFound:
                  value:
                    message: Layer name {layerName} is not exists
        '500':
          description: Ineternal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '501':
          description: >-
            Not Implemented, layer names that ends with '-redis' are not
            supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                LayerNotFound:
                  value:
                    message: Layer names that ends with '-redis' are not supported
  /layer/{name}:
    get:
      operationId: getLayer
      deprecated: true
      tags:
        - Layer
      summary: get existing layer
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getLayerResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Ineternal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
    put:
      operationId: updateLayer
      tags:
        - Layer
      summary: update existing layer source
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/layer'
        '201':
          description: Created
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/layer'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
              examples:
                LayerNotFound:
                  value:
                    message: Layer name {layerName} is not exists
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/layer'
  /layer/{layerName}/{cacheType}:
    get:
      operationId: getCache
      tags:
        - Layer
      summary: cache from sources of layer
      parameters:
        - name: layerName
          in: path
          required: true
          schema:
            type: string
        - name: cacheType
          in: path
          required: true
          schema:
            type: string
            enum:
              - s3
              - file
              - redis
              - geopackage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getCacheResponse'
              examples:
                file:
                  summary: file cache
                  value:
                    cacheName: example-layer
                    sources: []
                    grids:
                      - epsg4326dir
                    format: image/png
                    upscale_tiles: 18
                    minimize_meta_requests: true
                    cache:
                      type: file
                      directory: >-
                        /f9f92153-96e1-46fb-a44b-5c1b0955639c/c67ef7fb-a08c-41f8-ba4b-f2ba9a4b9a2a/
                      directory_layout: tms
                s3:
                  summary: s3 cache
                  value:
                    cacheName: example-layer
                    sources: []
                    grids:
                      - epsg4326dir
                    format: image/png
                    upscale_tiles: 18
                    minimize_meta_requests: true
                    cache:
                      type: s3
                      directory: >-
                        /5eedfc75-861c-42fc-81a9-ab2c0b95c274/d8527f15-5377-4a28-b5ce-92891d897aec/
                      directory_layout: tms
                      bucket_name: bucket-name
                geopackage:
                  summary: geopackage cache
                  value:
                    cacheName: example-layer
                    sources: []
                    grids:
                      - epsg4326dir
                    format: image/png
                    upscale_tiles: 18
                    minimize_meta_requests: true
                    cache:
                      type: geopackage
                      filename: /path/to/tiles/directory/example-layer.gpkg
                      table_name: example-layer
                redis:
                  summary: >-
                    redis cache, resolved by the '-redis' suffix. It carries no
                    upscale_tiles and no minimize_meta_requests.
                  value:
                    cacheName: example-layer-redis
                    sources:
                      - example-layer
                    grids:
                      - epsg4326dir
                    format: image/png
                    cache:
                      host: mapproxy-redis-master
                      port: 6379
                      type: redis
                      password: password
                      username: ''
                      default_ttl: 86400
        '400':
          description: Not valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: Ineternal Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
components:
  schemas:
    error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
    layer:
      type: object
      required:
        - cacheType
        - name
        - tilesPath
        - format
      properties:
        cacheType:
          type: string
          enum:
            - geopackage
            - s3
            - file
          example: s3
        name:
          type: string
          example: amsterdam_5cm
        tilesPath:
          type: string
          example: /path/to/tiles/directory/in/bucket/
        format:
          type: string
          enum:
            - PNG
            - JPEG
    getLayerResponse:
      type: object
      description: >-
        A cache as written in the mapproxy configuration. `cache`, the cache
        source, is absent on configuration entries that are not well formed
        caches, so it is not required.
      required:
        - grids
        - sources
        - upscale_tiles
        - format
      properties:
        cache:
          type: object
          properties:
            type:
              type: string
            directory:
              type: string
            directory_layout:
              type: string
        grids:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        upscale_tiles:
          type: number
        format:
          type: string
          enum:
            - image/png
            - image/jpeg
    fileCache:
      type: object
      description: >-
        A file cache source. Only `type` is guaranteed; a cache source missing
        an optional field is still a valid response.
      required:
        - type
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - file
        directory:
          type: string
          example: >-
            /f9f92153-96e1-46fb-a44b-5c1b0955639c/c67ef7fb-a08c-41f8-ba4b-f2ba9a4b9a2a/
        directory_layout:
          type: string
          example: tms
    s3Cache:
      type: object
      description: >-
        An s3 cache source. Only `type` is guaranteed; a cache source missing an
        optional field is still a valid response.
      required:
        - type
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - s3
        directory:
          type: string
          example: >-
            /5eedfc75-861c-42fc-81a9-ab2c0b95c274/d8527f15-5377-4a28-b5ce-92891d897aec/
        directory_layout:
          type: string
          example: tms
        use_http_get:
          type: boolean
        bucket_name:
          type: string
          example: bucket-name
    redisCache:
      type: object
      description: >-
        A redis cache source. Only `type` is guaranteed; a cache source missing
        an optional field is still a valid response.
      required:
        - type
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - redis
        host:
          type: string
          example: mapproxy-redis-master
        port:
          type: integer
          example: 6379
        username:
          type: string
          example: ''
        password:
          type: string
          example: password
        prefix:
          type: string
        default_ttl:
          type: integer
          example: 86400
    geopackageCache:
      type: object
      description: >-
        A geopackage cache source. Only `type` is guaranteed; a cache source
        missing an optional field is still a valid response.
      required:
        - type
      additionalProperties: true
      properties:
        type:
          type: string
          enum:
            - geopackage
        filename:
          type: string
          example: /path/to/tiles/directory/amsterdam_5cm.gpkg
        table_name:
          type: string
          example: amsterdam_5cm
    getCacheResponse:
      type: object
      description: >-
        The whole cache as written in the mapproxy configuration, alongside its
        name. Only `cacheName` and `cache` are guaranteed: the cache is returned
        verbatim, so mapproxy options this service does not model are present
        too, and options a cache genuinely lacks are absent rather than null or
        defaulted.
      required:
        - cacheName
        - cache
      additionalProperties: true
      properties:
        cacheName:
          type: string
          description: >-
            The resolved cache name, which for a redis request is the '-redis'
            suffixed name rather than the requested layer name.
          example: example-layer
        sources:
          type: array
          items:
            type: string
        grids:
          type: array
          items:
            type: string
        format:
          type: string
          example: image/png
        upscale_tiles:
          type: number
          example: 18
        minimize_meta_requests:
          type: boolean
        cache:
          oneOf:
            - $ref: '#/components/schemas/fileCache'
            - $ref: '#/components/schemas/s3Cache'
            - $ref: '#/components/schemas/redisCache'
            - $ref: '#/components/schemas/geopackageCache'
          discriminator:
            propertyName: type
            mapping:
              file: '#/components/schemas/fileCache'
              s3: '#/components/schemas/s3Cache'
              redis: '#/components/schemas/redisCache'
              geopackage: '#/components/schemas/geopackageCache'
    getConfigResponse:
      type: object
      properties:
        grids:
          type: object
          properties:
            grid:
              type: object
              properties:
                name:
                  type: string
                srs:
                  type: string
                origin:
                  type: string
                min_res:
                  type: number
                num_levels:
                  type: number
                bbox:
                  type: array
                  items:
                    type: number
        caches:
          type: object
          properties:
            cache:
              type: object
              properties:
                type:
                  type: string
                directory:
                  type: string
                directory_layout:
                  type: string
                grids:
                  type: array
                  items:
                    type: string
                format:
                  type: string
                  enum:
                    - image/png
                    - image/jpeg
                sources:
                  type: array
                  items:
                    type: string
                upscale_tiles:
                  type: number
                minimize_meta_request:
                  type: boolean
        layers:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              title:
                type: string
              sources:
                type: array
                items:
                  type: string
        globals:
          type: object
          properties:
            cache:
              type: object
            image:
              type: object
        sources:
          type: object
        services:
          type: object
    getConfigYamlResponse:
      type: string
    failedRemoveDiscreteLayers:
      type: array
      items:
        type: string
      example:
        - amsterdam_5cm
        - amsterdam_5cm-ortho