swagger: "2.0"
info:
  description: "A microserivce that serves ZRN data artifacts as web resources on the cloud"
  version: "1.1.0"
  title: "service_area_data"
  contact:
    name: "Maestro"
    email: "maestro-dev@zoox.com"
    url: "https://git.zooxlabs.com/zooxco/driving"
schemes:
  - "http"
basePath: /v1

paths:
  /service_areas/:
    get:
      summary: "get all service areas"
      x-swagger-router-controller: "dispatch.service_area_data.src.controller"
      operationId: "get_service_areas"
      produces:
        - application/json
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/ServiceAreasResponse"
        "400":
          description: "Invalid parameter was provided."
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Unknown internal error."
          schema:
            $ref: "#/definitions/ErrorResponse"

  /service_areas/{service_area_id}:
     get:
      summary: "get a service area by its id"
      x-swagger-router-controller: "dispatch.service_area_data.src.controller"
      operationId: "get_service_area_by_id"
      parameters:
        - in: "path"
          name: "service_area_id"
          description: "Id of the service area"
          type: "string"
          required: true
      produces:
        - application/json
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/ServiceArea"
        "400":
          description: "Invalid parameter was provided."
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Unknown internal error."
          schema:
            $ref: "#/definitions/ErrorResponse"

  /point_of_interests/:
    get:
      summary: "get point of interests"
      x-swagger-router-controller: "dispatch.service_area_data.src.controller"
      operationId: "get_point_of_interests"
      produces:
        - application/json
      parameters:
        - in: "query"
          name: "point_ids"
          description: "A list of point ids"
          type: "array"
          items:
            type: "string"
          required: true
          default: []
      responses:
        "200":
          description: "Operation was successful"
          schema:
            $ref: "#/definitions/PointOfInterestList"
        "404":
          description: "Points with the ids was not found"
          schema:
            $ref: "#/definitions/ErrorResponse"
        "500":
          description: "Unknown internal error."
          schema:
            $ref: "#/definitions/ErrorResponse"

definitions:
  ServiceAreasResponse:
    description: "A list of service areas"
    type: "object"
    properties:
      items:
        type: "array"
        description: "Provides a list of service areas"
        items:
          $ref: "#/definitions/ServiceArea"
      metadata:
        $ref: "#/definitions/ListMetaData"
  ServiceArea:
    description: "An area where Zoox runs operations. Operations include but are not limited to R&D, geofence validation, pilot programs, and production services"
    type: "object"
    properties:
      id:
        type: "string"
        description: "Unique ID to identify the geofence"
        readOnly: true
      name:
        type: "string"
        description: "Name of the service area"
      area_type:
        $ref: "#/definitions/AreaType"
      polygon:
        type: "array"
        items:
          $ref: "#/definitions/Point"
      point_of_interest_list:
        type: "array"
        items:
          $ref: "#/definitions/PointOfInterest"
      release_status:
        $ref: "#/definitions/ReleaseStatus"
  PointOfInterestList:
    description: "A list of points of interests"
    type: "array"
    items:
      $ref: "#/definitions/PointOfInterest"
  PointOfInterest:
    description: "A point that has special operational meaning, e.g. serves as a PU/DO location in a service area."
    type: "object"
    properties:
      id:
        type: "string"
        description: "Unique id for a point"
      name:
        type: "string"
      location:
        $ref: "#/definitions/Point"
      release_status:
        $ref: "#/definitions/ReleaseStatus"
  PointList:
    description: "A list of points"
    type: "array"
    items:
      $ref: "#/definitions/Point"
  Point:
    type: "array"
    description: "A point is a geo location in latitude and longitude format. It's the building block for other geo data structures"
    items:
      type: "number"
      format: "double"
      description: "coordinate"
  ReleaseStatus:
    type: "string"
    description: "The release status describes at what stage the underling map of this area is with regard to the map validation process"
    enum:
      - "INVALID_STATUS"
      - "ALPHA"
      - "BETA"
      - "RELEASE"
      - "P2P"
  AreaType:
    type: "string"
    description: "The area type annotates what types of service is enabled or disabled for an operational area"
    enum:
      - INVALID_TYPE
      - P2P
      - RESTRICTED
      - PICKUPS_EXCLUDED
      - OUT_OF_ODD
  ErrorResponse:
    type: "object"
    properties:
      message:
        description: "A message describing the error"
        type: "string"
  ListMetaData:
    type: "object"
    description: "Provides the meta data for various list resources"
    properties:
      orderBy:
        type: "string"
        description: "Resource's property on which resources are sorted"
      direction:
        type: "string"
        description: "Direction of the sorting order"
        enum:
          - "ASCENDING"
          - "DESCENDING"
      totalCount:
        type: "integer"
        description: "Total number of resources available"
    required:
      - totalCount
