openapi: 3.0.3
info:
  title: Common principles of Mapy.com REST API
  description: |
    ## Basic
    REST API Mapy.com is based on REST principles, all you need to use it is your browser or any other http client.

    ## API access
    Most services that the API provides require an API key to access. To obtain an API key, follow the instructions in the [Mapy.com API documentation](https://developer.mapy.com/en/rest-api-mapy-cz/how-to-start/).
    The API key must be sent in each request either in the request header named ``X-MAPY-API-KEY`` or in the query parameter named ``apiKey``

    ## Troubleshooting
    A unique identifier is added to the header ``X-Correlation-Id`` of each response to make it easier to find possible errors.

    ## Allowed HTTPS requests
    * ``GET``: Get a resource or list of resources
    * ``POST``: To create or update resource
    * ``PUT``: Update existing resource
    * ``DELETE``: To delete resource

    ## Description Of Usual Server Responses
    * ``200 OK`` - the request was successful (some API calls may return 201 instead).
    * ``201 Created`` - the request was successful and a resource was created.
    * ``204 No Content`` - the request was successful but there is no representation to return (i.e. the response is empty).
    * ``400 Bad Request`` - the request could not be understood or was missing required parameters.
    * ``422 Unprocessable Entity`` - the request could not be understood or was missing required parameters.
    * ``401 Unauthorized`` - API key is missing.
    * ``403 Forbidden`` - Invalid API key or service not enabled for API key.
    * ``404 Not Found`` - resource was not found.
    * ``405 Method Not Allowed`` - requested method is not supported for resource.
    * ``500 Internal Server Error`` - The server has encountered a situation it does not know how to handle.
    * ``503 Service Unavailable`` - The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.


  version: 1.0.0
servers:
  - url: https://api.mapy.com
    description: Production
security:
  - queryApiKey: []
  - headerApiKey: []
paths:
  /v1/example:
    get:
      summary: Example service.
      description: Example service.  Demonstrates basic usage and common responses for most of api services.
      tags:
        - "example"
      operationId: example
      responses:
        200:
          description: Success response. Depends on service implementation
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        400:
          description: Bad request. the request could not be understood or was missing required parameters.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorResponse"
        401:
          description: Unauthorized.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"

          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Api key not found"
        403:
          description: Forbidden.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Service not allowed for api key"
                  - msg: "Api key not valid"
        404:
          description: Not found.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Data not found"
        405:
          description: Method Not Allowed.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Method Not Allowed"
        422:
          description: Unprocessable Entity. the request could not be understood or was missing required parameters.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationErrorResponse"

        500:
          description: Internal server error.
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Internal server error"
        503:
          description: Service Unavailable
          headers:
            X-Correlation-Id:
              $ref: "#/components/headers/X-Correlation-Id"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                detail:
                  - msg: "Service Unavailable"
components:
  securitySchemes:
    headerApiKey:
      type: apiKey
      in: header
      name: X-MAPY-API-KEY
    queryApiKey:
      type: apiKey
      in: query
      name: apiKey
  headers:
    X-Correlation-Id:
      description: A unique identifier attached to each response for troubleshooting.
      schema:
        $ref: "#/components/schemas/CorrelationId"
  schemas:
    CorrelationId:
      title: CorrelationId
      description: A Correlation ID is a unique, randomly generated identifier value that is added to every response.
      type: string
    SuccessResponse:
      title: Success response
      type: object
      properties:
        data:
          type: string
          example: "Success"
    ValidationError:
      title: Validation Error
      required:
        - loc
        - msg
        - type
      type: object
      properties:
        loc:
          title: Array describes the attribute for which the error occurred.
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
        ctx:
          title: Error context
          type: object
    GenericError:
      title: Generic Error
      required:
        - msg
      type: object
      properties:
        msg:
          title: Message
          type: string

    ValidationErrorResponse:
      title: Validation error response
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'

    ErrorResponse:
      title: Generic error response
      type: object
      properties:
        detail:
          title: Detail
          type: array
          items:
            $ref: '#/components/schemas/GenericError'
