swagger.v2.yaml

---
swagger: '2.0'

################################################################################
# API Information
################################################################################
info:
  title: GRiD API v2
  description: |
    This is the API v2 specification for the Geospatial Repository and 
    Data Management System (aka GRiD).
    
    All calls require basic authentication. They also require an API key 
    (passed as the parameter `source`). API keys can be generated by visiting 
    https://rsgis.erdc.dren.mil/te_ba/api/source/list/.
    
    Unless otherwise noted, successful calls will return an HTTP status code 
    `200` with the appropriate response body. Server-side errors will return an 
    HTTP status code `5xx` with a JSON encoded error message, while client-side 
    errors will return an HTTP status code `4xx` with a JSON encoded error 
    message.
    
    # Changes from v1
    
    Changes to the API endpoints from v1 to v2 are relatively minor. We have
    added the ability to edit and delete both AOIs and Exports. You can also
    query point cloud and raster products (previously called collects) for
    additional file details.
    
    Point cloud and raster generation endpoints have changed the most, now
    providing more control over the export generation process with additional,
    optional parameters. Some of the parameters have also had name changes.
    Finally, the generation response now includes both a `task_id` to monitor
    status as well as the `export_id` for the resulting export.
    
    The bulk of the API changes will be found in the JSON-encoded responses,
    where we strove for more consistent naming of common fields and a flatter
    structure to the overall content, while increasing the amount of information
    provided to the user.
    
    Finally, beginning with v2, we have begun to manage the API specification
    using Swagger v2.0 (http://swagger.io/). The Swagger file can be used by a
    number of tools to explore the API. We like to use Postman
    (https://www.getpostman.com/), which can directly import Swagger files.
  version: "2.0.0"
  contact:
    name: GRiD Support
    email: GRiD.Core.Team@erdc.dren.mil
    
################################################################################
# Other root-level fixed fields
################################################################################
host: rsgis.erdc.dren.mil
schemes:
  - https
securityDefinitions:
  grid_auth:
    type: basic
security:
  - grid_auth: []
basePath: /te_ba/api/v2
produces:
  - application/json
tags:
  - name: AOI
    description: AOI resources.
  - name: Export
    description: Export resources.
  - name: Product
    description: Product resources.
  - name: Geoname
    description: Lookup geoname.
  - name: Task
    description: Task resources.

################################################################################
# Paths
################################################################################
paths:
  /aoi:
    get:
      tags:
        - AOI
      summary: Get a User's AOI List
      description: |
        Get a list of the AOIs created by or shared with the current GRiD user.
      parameters:
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: geom
          in: query
          description: A WKT geometry used to filter AOI results.
          required: false
          type: string
      responses:
        200:
          description: An array of AOIs.
          schema:
            $ref: '#/definitions/AOIArray'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/add:
    get:
      tags:
        - AOI
      summary: Add AOI
      description: |
        Create a new AOI for the given geometry.
      parameters:
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: name
          in: query
          description: The name for the AOI.
          required: true
          type: string
        - name: geom
          in: query
          description: A WKT geometry describing the AOI.
          required: true
          type: string
        - name: subscribe
          in: query
          description: |
            True, False, T, F, 1, or 0. Default value is false.
          default: false
          required: false
          type: boolean
      responses:
        200:
          description: An AOI object.
          schema:
            $ref: '#/definitions/AOIDetail'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/{pk}:
    get:
      tags:
        - AOI
      summary: AOI Detail
      description: |
        Get information for a single AOI.
      parameters:
        - name: pk
          in: path
          description: The primary key for the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: An AOI object.
          schema:
            $ref: '#/definitions/AOIDetail'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/edit/{pk}:
    get:
      tags:
        - AOI
      summary: Edit AOI
      description: |
        Update an AOIs name, notes, or geometry. In order to change an AOI's
        geometry, it must contain 0 generated exports.
      parameters:
        - name: pk
          in: path
          description: The primary key of the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: name
          in: query
          description: The name for the AOI.
          required: false
          type: string
        - name: geom
          in: query
          description: A WKT geometry describing the AOI.
          required: false
          type: string
        - name: notes
          in: query
          description: The notes for the AOI.
          required: false
          type: string
      responses:
        200:
          description: An AOI object.
          schema:
            $ref: '#/definitions/AOIDetail'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/delete/{pk}:
    get:
      tags:
        - AOI
      summary: Delete AOI
      description: Delete an existing AOI.
      parameters:
        - name: pk
          in: path
          description: The primary key of the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: Succesful AOI deletion responds with an empty body.
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/{pk}/generate/pointcloud:
    get:
      tags:
        - AOI
      summary: Generate Pointcloud Export
      description: |
        Generate pointcloud export for the given AOI and collect primary keys.
      parameters:
        - name: pk
          in: path
          description: The primary key for the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: products
          in: query
          description: |
            A list of product primary keys to include in the export, separated 
            by + or ,.
          required: true
          type: string
        - name: name
          in: query
          description: An optional name for the export.
          required: false
          type: string
        - name: intensity
          in: query
          description: Whether or not to export intensity. Default is true.
          default: true
          required: false
          type: boolean
        - name: dim_classification
          in: query
          description: Whether or not to export classification. Default is true.
          default: true
          required: false
          type: boolean
        - name: hsrs
          in: query
          description: Accepts an EPSG code. Defaults to AOI SRS.
          required: false
          type: string
        - name: file_export_options
          in: query
          description: |
            Determine file merging strategy. Accepts individual and collect. 
            Default is individual.
          required: false
          type: string
        - name: file_export_format
          in: query
          description: |
            Determine the format of the output file. Valid values are las12, 
            las14, nitf, pdf, and bpf3. Default is las12.
          required: false
          type: string
        - name: compressed
          in: query
          description: |
            Whether or not to export compressed data. Default is true.
          default: true
          required: false
          type: boolean
        - name: send_email
          in: query
          description: |
            Whether or not to notify user via email upon completion. Default is 
            false.
          default: false
          required: false
          type: boolean
        - name: generate_dem
          in: query
          description: |
            Whether or not to generate a DEM from the pointcloud. Default is 
            false.
          default: false
          required: false
          type: boolean
        - name: cell_spacing
          in: query
          description: |
            Used together with generate_dem. Default is 1.0. Ignored for 
            raster types.
          required: false
          type: number
          format: float
        - name: pcl_terrain
          in: query
          description: |
            Used to trigger a PMF Bare Earth export. Accepts ubran, suburban, 
            mountainous, and foliated. Default is none. Cannot be used with 
            sri_hres option.
          required: false
          type: string
        - name: sri_hres
          in: query
          description: |
            Used to trigger a Sarnoff Bare Earth export. Accepts the horizontal 
            resolution. Default is none. Cannot be used with pcl_terrain option.
          required: false
          type: number
          format: float
        - name: decimation_radius
          in: query
          description: |
            The minimum distance between points. If a neighboring point is
            found within this radius, it will be discarded. Uses PDAL
            decimation filter. Default is none.
          required: false
          type: number
          format: float
        - name: retile_size
          in: query
          description: |
            How many points to fit into each tile. The number of points in each 
            tile will not exceed this value, and will sometimes be less than 
            it. Uses PDAL chipper filter. Cannot be used with retile_area 
            option. Default is none.
          required: false
          type: integer
        - name: retile_area
          in: query
          description: |
            The target length of generated tiles. Units determined by source 
            data. Uses PDAL splitter filter. Cannot be used with retile_size 
            option. Default is none.
          required: false
          type: number
          format: float
      responses:
        200:
          description: A generate export object.
          schema:
            $ref: '#/definitions/GenerateExport'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /aoi/{pk}/generate/raster:
    get:
      tags:
        - AOI
      summary: Generate Raster Export
      description: |
        Generate raster export for the given AOI and collect primary keys.
      parameters:
        - name: pk
          in: path
          description: The primary key for the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: products
          in: query
          description: |
            A list of product primary keys to include in the export, separated 
            by + or ,.
          required: true
          type: string
        - name: name
          in: query
          description: An optional name for the export.
          required: false
          type: string
        - name: intensity
          in: query
          description: Whether or not to export intensity. Default is true.
          default: true
          required: false
          type: boolean
        - name: dim_classification
          in: query
          description: Whether or not to export classification. Default is true.
          default: true
          required: false
          type: boolean
        - name: hsrs
          in: query
          description: Accepts an EPSG code. Defaults to AOI SRS.
          required: false
          type: string
        - name: file_export_options
          in: query
          description: |
            Determine file merging strategy. Accepts individual and collect. 
            Default is individual.
          required: false
          type: string
        - name: file_export_format
          in: query
          description: |
            Determine the format of the output file. Valid values are GTiff and 
            NITF. Default is GTiff.
          required: false
          type: string
        - name: compressed
          in: query
          description: |
            Whether or not to export compressed data. Default is true.
          default: true
          required: false
          type: boolean
        - name: send_email
          in: query
          description: |
            Whether or not to notify user via email upon completion. Default is 
            false.
          default: false
          required: false
          type: boolean
      responses:
        200:
          description: A generate export object.
          schema:
            $ref: '#/definitions/GenerateExport'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /export/{pk}:
    get:
      tags:
        - Export
      summary: Get export details.
      description: Get information for a single export.
      parameters:
        - name: pk
          in: path
          description: The primary key of the AOI.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: An export object.
          schema:
            $ref: '#/definitions/ExportDetail'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /export/edit/{pk}:
    get:
      tags:
        - Export
      summary: Edit export
      description: Updates an exports name or notes.
      parameters:
        - name: pk
          in: path
          description: The primary key of the export.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: name
          in: query
          description: The name for the export.
          required: false
          type: string
        - name: notes
          in: query
          description: The notes for the export.
          required: false
          type: string
      responses:
        200:
          description: An export object.
          schema:
            $ref: '#/definitions/ExportDetail'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /export/delete/{pk}:
    get:
      tags:
        - Export
      summary: Delete export
      description: Deletes an existing export.
      parameters:
        - name: pk
          in: path
          description: The primary key of the export.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: Succesful export deletion responds with an empty body.
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /product/{pk}:
    get:
      tags:
        - Product
      summary: Get product details
      description: Get information for a single product (pointcloud or raster).
      parameters:
        - name: pk
          in: path
          description: The primary key of the product.
          required: true
          type: integer
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: A product (pointcloud or raster) object.
          schema:
            $ref: '#/definitions/ProductJSON'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /geoname:
    get:
      tags:
        - Geoname
      summary: Lookup Geoname
      description: |
        Get suggested AOI name based on geographic coordinates of the geometry.
      parameters:
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
        - name: geom
          in: query
          description: A WKT geometry describing the AOI.
          required: true
          type: string
      responses:
        200:
          description: A geoname object.
          schema:
            type: object
            properties:
              geom:
                type: string
                description: The WKT geometry describing the AOI.
              name:
                type: string
                description: The suggested name for the given geometry.
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /task/{task_id}:
    get:
      tags:
        - Task
      summary: Get task details
      description: Get task status/details for the provided task_id.
      parameters:
        - name: task_id
          in: path
          description: The ID of the task.
          required: true
          type: string
        - name: source
          in: query
          description: Your GRiD generated API key.
          required: true
          type: string
      responses:
        200:
          description: A task object.
          schema:
            $ref: '#/definitions/Task'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
definitions:
  AOIArray:
    type: object
    properties:
      aoi_list:
        type: array
        items:
          $ref: '#/definitions/AOIList'
        description: A list of AOIs.
  AOIDetail:
    type: object
    properties:
      name:
        $ref: '#/definitions/Name'
      created_at:
        $ref: '#/definitions/CreatedAt'
      is_active:
        type: boolean
        description: Whether or not the AOI is active.
      source:
        type: string
        description: Source of the AOI (e.g., map, api).
      user:
        $ref: '#/definitions/User'
      geometry:
        type: string
        description: The WKT geometry of the AOI.
      notes:
        $ref: '#/definitions/Notes'
      pk:
        $ref: '#/definitions/Pk'
      export_set:
        type: array
        items:
          $ref: '#/definitions/Export'
        description: The exports of the AOI.
      pointcloud_intersects:
        type: array
        items:
          $ref: '#/definitions/PointcloudDatasetSimple'
        description: The pointcloud products for the AOI.
      raster_intersects:
        type: array
        items:
          $ref: '#/definitions/RasterDatasetSimple'
        description: The raster products for the AOI.
  AOIList:
    type: object
    properties:
      name:
        $ref: '#/definitions/Name'
      created_at:
        $ref: '#/definitions/CreatedAt'
      is_active:
        type: boolean
        description: Whether or not the AOI is active.
      source:
        type: string
        description: Source of the AOI (e.g., map, api).
      user:
        $ref: '#/definitions/User'
      geometry:
        type: string
        description: The WKT geometry of the AOI.
      notes:
        $ref: '#/definitions/Notes'
      pk:
        $ref: '#/definitions/Pk'
  Area:
    type: number
    format: float
    description: The area of the geometry in sq_km.
  CellSpacing:
    type: number
    format: float
    description: The cell spacing used in DEM generation, if applicable.
  Classification:
    type: string
    description: The classifications selected for the export.
  CollectedAt:
    type: string
    format: date-time
    description: The date of collection. ISO 8601 format as UTC.
  PercentCoverage:
    type: number
    format: float
    description: |
      The percent of the product area covered by the AOI. Only available in AOI 
      detail.
  CreatedAt:
    type: string
    format: date-time
    description: The date of AOI creation. ISO 8601 format as UTC.
  Datatype:
    type: string
    description: The datatype (e.g., LAS 1.2, DTM).
  DimClassification:
    type: boolean
    description: |
      Whether or not Classification dimension is included in exported data.
  Error:
    type: object
    properties:
      error:
        type: string
        description: Description of the error from the given API request.
  Export:
    type: object
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      user:
        $ref: '#/definitions/User'
      hsrs:
        $ref: '#/definitions/HSRS'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      started_at:
        $ref: '#/definitions/StartedAt'
      status:
        $ref: '#/definitions/Status'
      url:
        $ref: '#/definitions/URL'
  ExportDetail:
    type: object
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      user:
        $ref: '#/definitions/User'
      hsrs:
        $ref: '#/definitions/HSRS'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      started_at:
        $ref: '#/definitions/StartedAt'
      status:
        $ref: '#/definitions/Status'
      url:
        $ref: '#/definitions/URL'
      rgb:
        $ref: '#/definitions/RGB'
      intensity:
        $ref: '#/definitions/Intensity'
      dim_classification:
        $ref: '#/definitions/DimClassification'
      file_export_options:
        $ref: '#/definitions/FileExportOptions'
      generate_dem:
        $ref: '#/definitions/GenerateDEM'
      cell_spacing:
        $ref: '#/definitions/CellSpacing'
      notes:
        $ref: '#/definitions/Notes'
      classification:
        $ref: '#/definitions/Classification'
      pcl_terrain:
        $ref: '#/definitions/PCLTerrain'
      sri_hres:
        $ref: '#/definitions/SRIHRES'
      exportfiles:
        $ref: '#/definitions/Exportfiles'
      tda_set:
        $ref: '#/definitions/TDASet'
      task_id:
        $ref: '#/definitions/TaskID'
  Exportfile:
    type: object
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      url:
        $ref: '#/definitions/URL'
  Exportfiles:
    type: array
    items:
      $ref: '#/definitions/Exportfile'
    description: The export files of the export.
  FileExportOptions:
    type: string
    description: |
      The file export options used (e.g., individual, collect, super).
  Filesize:
    type: integer
    description: The size of the product on the filesystem in bytes.
  GenerateDEM:
    type: boolean
    description: Whether or not this was a generated DEM from pointcloud.
  GenerateExport:
    type: object
    properties:
      export_id:
        type: integer
        description: The ID of the resulting export.
      task_id:
        type: string
        description: The ID of the task.
  Geometry:
    type: string
    description: |
      The WKT geometry of the product. Only available in product detail.
  HSRS:
    type: string
    description: The horizontal spatial reference system EPSG code.
  Intensity:
    type: boolean
    description: |
      Whether or not Intensity dimension is included in exported data.
  Name:
    type: string
    description: The name of the export.
  Notes:
    type: string
    description: User notes.
  PCLTerrain:
    type: string
    description: The PCL terrain option of the export.
  Pk:
    type: integer
    description: The primary key of the product.
  ProductJSON:
    type: object
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      sensor:
        $ref: '#/definitions/Sensor'
      collected_at:
        $ref: '#/definitions/CollectedAt'
      classification:
        $ref: '#/definitions/SecurityClassification'
      area:
        $ref: '#/definitions/Area'
      filesize:
        $ref: '#/definitions/Filesize'
      point_count:
        type: integer
        description: The total number of points in the product (pointcloud products only).
      density:
        type: number
        format: float
        description: The average point density of the product (pointcloud products only).
      percent_coverage:
        $ref: '#/definitions/PercentCoverage'
      geometry:
        $ref: '#/definitions/Geometry'
  PointcloudDatasetSimple:
    type: object
    description: |
      The simplified point cloud product object lacks the geometry. This is only
      calculated when point cloud products are queried via the 
      `/pointcloud/{pk}` endpoint.
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      sensor:
        $ref: '#/definitions/Sensor'
      collected_at:
        $ref: '#/definitions/CollectedAt'
      classification:
        $ref: '#/definitions/SecurityClassification'
      area:
        $ref: '#/definitions/Area'
      filesize:
        $ref: '#/definitions/Filesize'
      point_count:
        type: integer
        description: The total number of points in the product.
      density:
        type: number
        format: float
        description: The average point density of the product.
      percent_coverage:
        $ref: '#/definitions/PercentCoverage'
  RasterDatasetSimple:
    type: object
    properties:
      datatype:
        $ref: '#/definitions/Datatype'
      name:
        $ref: '#/definitions/Name'
      pk:
        $ref: '#/definitions/Pk'
      sensor:
        $ref: '#/definitions/Sensor'
      collected_at:
        $ref: '#/definitions/CollectedAt'
      classification:
        $ref: '#/definitions/SecurityClassification'
      area:
        $ref: '#/definitions/Area'
      filesize:
        $ref: '#/definitions/Filesize'
      percent_coverage:
        $ref: '#/definitions/PercentCoverage'
  RGB:
    type: boolean
    description: Whether or not RGB dimension is included in exported data.
  SecurityClassification:
    type: string
    description: The security classification.
  Sensor:
    type: string
    description: The sensor used to make the collection.
  SRIHRES:
    type: number
    format: float
    description: The sri_hres value of the export.
  StartedAt:
    type: string
    format: date-time
    description: Time of creation for the AOI. ISO 8601 format as UTC.
  Status:
    type: string
    description: The status of the export (e.g., SUCCESS, FAILED, QUEUED).
  Task:
    type: object
    properties:
      task_traceback:
        type: string
        description: The description of any failures if they occurred.
      task_state:
        type: string
        description: The state of the task (e.g., SUCCESS, FAILED, QUEUED).
      task_tstamp:
        type: string
        format: date-time
        description: ISO 8601 format as UTC.
      task_name:
        type: string
        description: The name of the task (e.g., export.tasks.generate_export).
      task_id:
        type: string
        description: The ID of the task.
  TaskID:
    type: string
    description: The ID of the associated task used for generation.
  TDA:
    type: object
    properties:
      created_at:
        $ref: '#/definitions/CreatedAt'
      name:
        $ref: '#/definitions/Name'
      notes:
        $ref: '#/definitions/Notes'
      pk:
        $ref: '#/definitions/Pk'
      status:
        $ref: '#/definitions/Status'
      tda_type:
        type: string
        description: The TDA type (eg., HLZ, LOS).
      url:
        $ref: '#/definitions/URL'
  TDASet:
    type: array
    items:
      $ref: '#/definitions/TDA'
    description: The TDA set of the export.
  URL:
    type: string
    description: The download URL of the export.
  User:
    type: integer
    description: The ID of the creating user.