api.yaml

openapi: 3.0.0
servers:
  - description: SwaggerHub API Auto Mocking
    url: https://localhost:8080/
info:
  title: DataFeeder API
  description: This API covers dataset upload and publishing features of the application
  version: "1.0.0"
  contact:
    email: psc@georchestra.org
tags:
  - name: File Upload
    description: 'API to control jobs related to form based file upload of geospatial datasets'
  - name: Data Publishing
    description: 'API to control jobs related to publishing geospatial datasets previously uploaded'

paths:
  /config/frontend:
    get:
      tags:
        - Config
      description: 'Get the front-end application configuration object'
      operationId: getFrontendConfig
      responses:
        200:
          description: Front-end application configuration object
          content:
            application/json:
              schema:
                type: object
        401:
          description: 'Not authenticated'

  /upload:
    post:
      tags:
        - File Upload
      description: Upload one or multiple files to the server, and get a handle to the job.
                   Once the files are uploaded, the analysis process is automatically triggered. Its status can be polled with GET /upload/{jobId}
      operationId: uploadFiles
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                filename:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        200:
          $ref: '#/components/responses/UploadStatusResponse'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges to upload files'
    get:
      tags:
        - File Upload
      description: 'Poll the status of all the upload jobs owned by the calling user'
      operationId: findUserUploadJobs
      responses:
        200:
          $ref: '#/components/responses/UploadStatusResponseList'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges to query other users jobs'

  /upload/all:
    get:
      tags:
        - File Upload
      description: 'Poll the status of all the upload jobs. Access restricted to administrators'
      operationId: findAllUploadJobs
      responses:
        200:
          $ref: '#/components/responses/UploadStatusResponseList'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges to upload files'
  
  /upload/{jobId}:
    get:
      tags:
        - File Upload
      description: 'Poll the status of a given upload job by id'
      operationId: findUploadJob
      parameters:
      - $ref: '#/components/parameters/jobId'
      responses:
        200:
          $ref: '#/components/responses/UploadStatusResponse'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'
    delete:
      tags:
        - File Upload
      description: 'Remove a job and all its resources (e.g. temporary files). Does not unpublish. Use abort=true to abort a running analysis or publishing job'
      operationId: removeJob
      parameters:
      - $ref: '#/components/parameters/jobId'
      - name: abort
        in: query
        description: If true, abort the dataset analysis or publishing, if running. Defaults to false
        required: false
        schema:
          type: boolean
          default: false
      responses:
        204:
          description: 'Job removed.'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'
        409:
          description: 'Conflict. The abort=true parameter was not provided and the analysis or publishing job is running'

  /upload/{jobId}/{typeName}/sampleFeature:
    get:
      tags:
        - File Upload
      operationId: getSampleFeature
      description: Obtain a sample dataset feature in GeoJSON format, optionally specifying a feature index, crs, and/or dataset's character encoding.
                   The response encoding is always UTF-8. The 'encoding' parameter can be used to force reading the native data in a different charset.
                   The returned geometry CRS is controlled by the "srs", and "srsOverride" query parameters.
                   If none is provided, the geometry is returned as-is, in the dataset's native CRS (possibly null).
                   The "srsOverride" parameter allows to override the dataset's native CRS, which also means assuming a native CRS when the
                   dataset didn't provide a native CRS (e.g. a shapefile uploaded without .prj side-car file).
                   The "srs" parameter specifies the output geometry CRS. The geometry will be reprojected from the source CRS to the output CRS.
      parameters:
      - $ref: '#/components/parameters/jobId'
      - $ref: '#/components/parameters/typeName'
      - name: featureIndex
        in: query
        description: Optional feature index, if unspecified, the first feature (index 0) is returned
        required: false
        schema:
          type: integer
          format: int32
          minimum: 0
      - name: encoding
        in: query
        description: Optional, force dataset encoding
        required: false
        schema:
          type: string
      - name: srs
        in: query
        description: Optional, coordinate reference system (e.g. 'EPSG:3857')
        required: false
        schema:
          type: string
      - name: srsOverride
        in: query
        description: Optional, EPSG SRS used to override the native CRS, or assume a native SRS when the native CRS is unknown (for example, a shapefile uploaded without .prj side-car file).
                     This allows to request a feature using a source CRS for datasets that do not specify a native CRS, and still get a reprojected response to
                     another CRS in combination with the "srs" parameter.
        required: false
        schema:
          type: string
        example: EPSG:4326
      responses:
        202:
          $ref: '#/components/responses/SampleFeatureResponse'
        400:
          description: 'Bad request. Some parameter is not acceptable or missing'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'

  /upload/{jobId}/{typeName}/bounds:
    get:
      tags:
        - File Upload
      operationId: getBounds
      description: Get the bounding box of the dataset, optionally indicating the CRS and whether to reproject from the native CRS to the new one
                   The returned geometry CRS is controlled by the "srs", and "srsOverride" query parameters.
                   If none is provided, the geometry is returned as-is, in the dataset's native CRS (possibly null).
                   The "srsOverride" parameter allows to override the dataset's native CRS, which also means assuming a native CRS when the
                   dataset didn't provide a native CRS (e.g. a shapefile uploaded without .prj side-car file).
                   The "srs" parameter specifies the output geometry CRS. The geometry will be reprojected from the source CRS to the output CRS.
      parameters:
      - $ref: '#/components/parameters/jobId'
      - $ref: '#/components/parameters/typeName'
      - name: srs
        in: query
        description: Optional, output coordinate reference system (e.g. 'EPSG:3857')
        required: false
        schema:
          type: string
      - name: srsOverride
        in: query
        description: Optional, EPSG SRS used to override the native CRS, or assume a native SRS when the native CRS is unknown (for example, a shapefile uploaded without .prj side-car file).
                     This allows to request the dataset bounds using a user defined native CRS for datasets that do not specify a native CRS, 
                     and still get a reprojected response to another CRS in combination with the "srs" parameter.
        required: false
        schema:
          type: string
        example: EPSG:4326
      responses:
        202:
          $ref: '#/components/responses/BoundingBoxResponse'
        400:
          description: 'Bad request. Some parameter is not acceptable or missing'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'

  /upload/{jobId}/publish:
    post:
      tags:
        - Data Publishing
      description: 'Publish the dataset(s) from the given upload'
      operationId: publish
      parameters:
      - $ref: '#/components/parameters/jobId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        202:
          $ref: '#/components/responses/PublishStatusResponse'
        400:
          description: 'Bad request. Some parameter is not acceptable or missing'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'
        409:
          description: 'Conflict. The upload is not ready for publishing.'
    get:
      tags:
        - Data Publishing
      description: 'Poll the publishing staus of the given job'
      operationId: getPublishingStatus
      parameters:
      - $ref: '#/components/parameters/jobId'
      responses:
        200:
          $ref: '#/components/responses/PublishStatusResponse'
        400:
          description: 'Bad request. Some parameter is not acceptable or missing'
        401:
          description: 'Not authenticated'
        403:
          description: 'Forbidden. User has no priviledges access the requested job'

components:
  parameters:
    jobId:
      name: jobId
      in: path
      description: Unique job identifier
      required: true
      schema:
        type: string
        format: uuid
    typeName:
      name: typeName
      in: path
      description: Feature type name
      required: true
      schema:
        type: string
  responses:
    UploadStatusResponseList:
      description: Processing status of a list of dataset upload job
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/UploadJobStatus'
    UploadStatusResponse:
      description: Processing status of a dataset upload job
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadJobStatus'
    PublishStatusResponse:
      description: Processing status of a dataset publishing job
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublishJobStatus'
    SampleFeatureResponse:
      description: Sample feature for an uploaded dataset
      content:
        application/geo+json:
          schema:
            type: object
    BoundingBoxResponse:
      description: dataset bounds in the requested CRS, if given, defaults to the native CRS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BoundingBox'
  schemas:
    AnalysisStatusEnum:
      type: string
      enum: [PENDING, ANALYZING, DONE, ERROR]
      description: aggregate of status of all datasets in the upload package. If any dataset status is PENDING, ANALYZING, or ERROR, that's the job's status.
        If at least one dataset status is ERROR, then the job status is ERROR. If no datasets where recognized in the upload, status is ERROR.
    PublishStatusEnum:
      type: string
      enum: [PENDING, RUNNING, DONE, ERROR]
    PublishStepEnum:
      type: string
      enum: [SKIPPED, SCHEDULED, DATA_IMPORT_STARTED, DATA_IMPORT_FINISHED, OWS_PUBLISHING_STARTED, OWS_PUBLISHING_FINISHED, METADATA_PUBLISHING_STARTED, METADATA_PUBLISHING_FINISHED, OWS_METADATA_UPDATE_STARTED, OWS_METADATA_UPDATE_FINISHED, COMPLETED]

    UploadJobStatus:
      type: object
      description: Describes the status of processing a dataset upload
      properties:
        jobId:
          type: string
          format: uuid
          description: Identifier for the upload processing job
        progress:
          description: Estimated completion progress, from 0 to 1.
          type: number
          format: double
          minimum: 0.0
          maximum: 1.0
          default: 0.0
        status:
          $ref: '#/components/schemas/AnalysisStatusEnum'
        error:
          type: string
          description: short description of the error that prevents the job to complete successfully
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/DatasetUploadStatus'

    DatasetUploadStatus:
      type: object
      description: Describes a recognized uploaded dataset
      properties:
        name:
          type: string
          description: Name of the dataset in the uploaded package
        status:
          $ref: '#/components/schemas/AnalysisStatusEnum'
        error:
          type: string
          description: short description of the error that prevents the dataset to be analysed
        featureCount:
          type: integer
          format: int32
          description: Number of features in the dataset
        nativeBounds:
          $ref: '#/components/schemas/BoundingBox'
        encoding:
          type: string
          description: detected charset
        options:
            type: object
            additionalProperties: true
            description: Extra options provided for the dataset
        format:
          type: string
          description: either SHP or CSV
    
    Property:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        type:
          type: string


    CRS:
      type: object
      description: Coordinate Reference System
      properties:
        srs:
          type: string
          description: Coordinate Reference System's EPSG identifier.
                       Can be null if a matching reference system couldn't be found in the EPSG database. 
        wkt:
          type: string
          description: Coordinate Reference System's Well Known Text representation. Despite the 'srs' identifier being found or not, the WKT representation is still available.
    BoundingBox:
      type: object
      properties:
        crs:
          $ref: '#/components/schemas/CRS'
        minx:
          type: number
          format: double
        maxx:
          type: number
          format: double
        miny:
          type: number
          format: double
        maxy:
          type: number
          format: double

    PublishRequest:
      type: object
      properties:
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/DatasetPublishRequest'

    DatasetMetadata:
      type: object
      description: User supplied dataset metadata information
      required:
      - title 
      - abstract
      properties:
        title:
          type: string
          description: Metadata title for the dataset
        abstract:
          type: string
          description: Metadata abtract text for the dataset
          maxLength: 4096
        tags:
          type: array
          description: metadata keyworkds for the dataset
          items:           
            type: string
        creationDate:
          description: Dataset creation date, in RFC3339 format
          type: string
          format: date
          example: 2017-07-21
        scale:
          description: Optional, scale the data was created for (e.g. 500000 for a 1:500000 scale)
          type: integer
          format: int32
          example: 25000
        creationProcessDescription:
          type: string
          description: textual description of dataset lineage
          maxLength: 4096
        options:
          type: object
          additionalProperties: true
          description: optional, extra options on the file format, mainly used for CSV.

    DatasetPublishRequest:
      type: object
      description: Name of the dataset in the uploaded package, necessary to identify which dataset to publish from the UploadJobStatus
      required:
      - nativeName
      - metadata 
      properties:
        nativeName:
          type: string
          description: Name of the dataset in the uploaded package, necessary to identify which dataset to publish from the UploadJobStatus
        publishedName:
          type: string
          description: Name under which the dataset is published to GeoServer, defaults to nativeName. It can be modified by the system to avoid duplicated layer names.
        encoding:
          type: string
          description: Specify which charset (e.g. ISO-8859-1, UTF-8, etc.) to interpret the dataset alphanumeric properties with. Takes effect only for uploaded shapefiles.
        srs:
          description: Optional, Coordinate Reference System identifier to publish the dataset in. If not provided, the dataset is published using the CRS inferred
                       during the upload analysis process. If no CRS identifier was determined, the job will fail.
          type: string
        srs_reproject:
          description: Optional, whether to reproject from the native CRS to the one provided in the srs parameter.
                       If false or not provided, the srs parameter overrides the native CRS without reprojection.
          type: boolean
          default: false
        metadata:
          $ref: '#/components/schemas/DatasetMetadata'

    PublishJobStatus:
      type: object
      description: Describes the processing status of a publishing job for a given upload
      properties:
        jobId:
          type: string
          format: uuid
          description: Identifier for the upload processing job
        progress:
          description: Estimated completion progress, from 0 to 1.
          type: number
          format: double
          minimum: 0.0
          maximum: 1.0
          default: 0.0
        status:
          $ref: '#/components/schemas/PublishStatusEnum'
        error:
          type: string
          description: short description of the error that prevents the job to complete successfully
        datasets:
          type: array
          items:
            $ref: '#/components/schemas/DatasetPublishingStatus'

    DatasetPublishingStatus:
      type: object
      description: Describes the status of publishing a given dataset
      properties:
        nativeName:
          type: string
          description: Name of the dataset in the uploaded package, necessary to identify which dataset to publish from the UploadJobStatus
        publishedWorkspace:
          type: string
          description: Name of the GeoServer workspace under which the dataset has been published.
        publishedName:
          type: string
          description: Final name under which the layer was published to GeoServer. It may have been modified from the requested layer name
                       in order to avoid duplication if a layer with such name already exists in the target GeoServer workspace.
        metadataRecordId:
          type: string
          description: Identifier for the metadta record created while publishing the dataset's metadata to GeoNetwork.
        title:
          type: string
        status:
          $ref: '#/components/schemas/PublishStatusEnum'
        error:
          type: string
          description: short description of the error that prevents the dataset to be published
        publish:
          type: boolean
          description: true if this dataset is scheduled to be published (as requested through a PublishRequest)
        progress:
          description: Estimated completion progress, from 0 to 1.
          type: number
          format: double
          minimum: 0.0
          maximum: 1.0
          default: 0.0
        progressStep:
          $ref: '#/components/schemas/PublishStepEnum'