openapi: 3.0.3
info:
  title: NASA Mars Rover Photos API
  description: >-
    The Mars Rover Photos API provides access to images collected by NASA's
    Curiosity, Opportunity, and Spirit rovers on Mars. Photos are organized
    by sol (Martian day) or Earth date and can be filtered by camera.
  version: 1.0.0
  contact:
    name: NASA API Support
    url: https://api.nasa.gov
servers:
  - url: https://api.nasa.gov
paths:
  /mars-photos/api/v1/rovers/{rover}/photos:
    get:
      operationId: getRoverPhotos
      summary: NASA Get photos from a Mars rover
      description: >-
        Returns photos taken by the specified Mars rover, filtered by sol
        or Earth date and optionally by camera.
      parameters:
        - name: rover
          in: path
          required: true
          description: The name of the rover.
          schema:
            type: string
            enum:
              - curiosity
              - opportunity
              - spirit
        - name: sol
          in: query
          required: false
          description: Martian sol (day) on which photos were taken.
          schema:
            type: integer
        - name: earth_date
          in: query
          required: false
          description: Earth date on which photos were taken (YYYY-MM-DD).
          schema:
            type: string
            format: date
        - name: camera
          in: query
          required: false
          description: Abbreviation of the camera used to take the photo.
          schema:
            type: string
            enum:
              - FHAZ
              - RHAZ
              - MAST
              - CHEMCAM
              - MAHLI
              - MARDI
              - NAVCAM
              - PANCAM
              - MINITES
        - name: page
          in: query
          required: false
          description: Page number for paginated results (25 items per page).
          schema:
            type: integer
            default: 1
        - name: api_key
          in: query
          required: true
          schema:
            type: string
            default: DEMO_KEY
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  photos:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoverPhoto'
      tags:
        - Mars Photos
  /mars-photos/api/v1/rovers/{rover}/latest_photos:
    get:
      operationId: getLatestRoverPhotos
      summary: NASA Get the latest photos from a Mars rover
      description: Returns the most recently available photos for a rover.
      parameters:
        - name: rover
          in: path
          required: true
          schema:
            type: string
            enum:
              - curiosity
              - opportunity
              - spirit
        - name: api_key
          in: query
          required: true
          schema:
            type: string
            default: DEMO_KEY
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  latest_photos:
                    type: array
                    items:
                      $ref: '#/components/schemas/RoverPhoto'
      tags:
        - Mars Photos
  /mars-photos/api/v1/manifests/{rover}:
    get:
      operationId: getRoverManifest
      summary: NASA Get mission manifest for a rover
      description: Returns the mission manifest including sol and photo counts.
      parameters:
        - name: rover
          in: path
          required: true
          schema:
            type: string
            enum:
              - curiosity
              - opportunity
              - spirit
        - name: api_key
          in: query
          required: true
          schema:
            type: string
            default: DEMO_KEY
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  photo_manifest:
                    $ref: '#/components/schemas/RoverManifest'
      tags:
        - Mars Photos
components:
  schemas:
    RoverPhoto:
      type: object
      properties:
        id:
          type: integer
          description: Unique identifier for the photo.
        sol:
          type: integer
          description: Martian sol on which the photo was taken.
        camera:
          $ref: '#/components/schemas/Camera'
        img_src:
          type: string
          format: uri
          description: URL of the image.
        earth_date:
          type: string
          format: date
          description: Earth date when the photo was taken.
        rover:
          $ref: '#/components/schemas/Rover'
    Camera:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        rover_id:
          type: integer
        full_name:
          type: string
    Rover:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        landing_date:
          type: string
          format: date
        launch_date:
          type: string
          format: date
        status:
          type: string
          enum:
            - active
            - complete
    RoverManifest:
      type: object
      properties:
        name:
          type: string
        landing_date:
          type: string
          format: date
        launch_date:
          type: string
          format: date
        status:
          type: string
        max_sol:
          type: integer
        max_date:
          type: string
          format: date
        total_photos:
          type: integer
        photos:
          type: array
          items:
            type: object
            properties:
              sol:
                type: integer
              earth_date:
                type: string
                format: date
              total_photos:
                type: integer
              cameras:
                type: array
                items:
                  type: string
tags:
  - name: Mars Photos