openapi: 3.1.0

info:
  title: DAS User Farms REST API
  summary: REST API for DAS user farms
  description: |-
    This API allows clients to list and retrieve user farms.
  termsOfService: https://map.dasintel.io/file/das_terms_of_service.pdf
  contact:
    name: Customer Support
    url: https://info.digitalagricultureservices.com/en-au/contact-us
    email: support@dasintel.io
  license:
    name: Apache 2.0
    identifier: Apache-2.0
  version: 0.2.0

jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base

servers:
  - url: https://api.dasintel.io
    description: Production server

paths:
  /user-farms:
    post:
      summary: Create a user farm from an address
      description: >-
        Creates a new user farm from the provided address and dispatches a webhook
        containing a link to the report for the newly created user farm.
      operationId: create-user-farm
      parameters:
        - in: header
          name: X-Api-Version
          description: The version of the API as a date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
            enum:
              - '2024-12-01'
        - in: header
          name: Accept
          description: The media type that the request will accept
          required: true
          schema:
            type: string
            enum:
              - application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createUserFarmRequest'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    format: uuid
                    examples:
                      - 'd290f1ee-6c54-4b01-90e6-d701748f0851'

        '400':
          description: Bad Request
        '401':
          description: API key is missing or invalid
          headers:
            WWW-Authenticate:
              schema:
                type: string
        '406':
          description: Not Acceptable
        '422':
          description: Unprocessable Entity — could not find the address
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
    get:
      summary: List user farms
      description: This resource represents a paginated list of user farms.
      operationId: list-user-farms
      parameters:
        - in: header
          name: X-Api-Version
          description: The version of the API as a date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
            enum:
              - '2024-12-01'
        - in: query
          name: page
          description: The page number to retrieve
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: pageSize
          description: The number of items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/userFarmList'
        '401':
          description: API key is missing or invalid
          headers:
            WWW-Authenticate:
              schema:
                type: string
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error
  /user-farms/{id}:
    get:
      summary: Get user farm
      description: >-
        This resource represents a user created farm. Each farm is identified by
        a unique ID. The farm is represented as a GeoJSON FeatureCollection.
      operationId: get-user-farm
      parameters:
        - in: header
          name: X-Api-Version
          description: The version of the API as a date in YYYY-MM-DD format
          required: true
          schema:
            type: string
            format: date
            enum:
              - '2024-12-01'
        - in: header
          name: Accept
          description: The media type that the request will accept
          schema:
            type: string
            enum:
              - application/geo+json
          required: true
        - in: path
          name: id
          description: The unique identifier of the user farm
          schema:
            type: string
            format: uuid
            examples:
              - d290f1ee-6c54-4b01-90e6-d701748f0851
          required: true
        - in: query
          name: includeBuildings
          description: Option to include building features in the response
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: OK
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/userFarmFeatureCollection'
        '401':
          description: API key is missing or invalid
          headers:
            WWW-Authenticate:
              schema:
                type: string
        '406':
          description: Not Acceptable
        '404':
          description: Not Found
        '429':
          description: Too Many Requests
        '500':
          description: Internal Server Error

webhooks:
  user-farm-property-report.ready:
    $ref: 'https://schema.dasintel.io/webhook/one-click-report.yaml#/webhooks/one-click-report.ready'

components:
  schemas:
    createUserFarmRequest:
      title: Create User Farm Request
      description: Request body for creating a new user farm from a given address
      type: object
      properties:
        address:
          description: Address used to derive the farm boundary
          type: string
          examples:
            - '123 Farm Road, Dubbo NSW 2830, Australia'
      required:
        - address
    userFarmList:
      title: User Farm List
      description: The user farm list represents a list of user farm list items
      type: array
      items:
        $ref: '#/components/schemas/userFarmListItem'
      minItems: 0
    userFarmListItem:
      title: User Farm List Item
      description: >-
        The user farm list item represents a user created farm and includes the
        unique ID
      type: object
      properties:
        id:
          description: Unique identifier of the user farm
          type: string
          format: uuid
          examples:
            - d290f1ee-6c54-4b01-90e6-d701748f0851
        clientId:
          description: Client identifier associated with the user farm
          type:
            - string
            - 'null'
          examples:
            - RW-1000
    userFarmFeatureCollection:
      title: User Farm Feature Collection
      description: >-
        The user farm feature collection represents a user created farm. The
        first element of the collection is a feature that represents the farm
        boundary and includes a properties field that contains the farm details,
        including a unique ID. Subsequent feature elements represent other
        geometrical objects that are contained within the farm boundary, for
        example, cadastres or buildings.
      type: object
      allOf:
        - $ref: https://geojson.org/schema/FeatureCollection.json
        - type: object
          properties:
            features:
              prefixItems:
                - $ref: https://schema.dasintel.io/das-api/schema/user-farm-feature.json
              items:
                oneOf:
                  - $ref: https://schema.dasintel.io/das-api/schema/cadastre-feature.json
                  - $ref: https://schema.dasintel.io/das-api/schema/building-feature.json
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        The API key is used to authenticate requests to the DAS User Farms API.
        It should be included in the header of each request.

security:
  - ApiKeyAuth: [ ]

externalDocs:
  description: More information on the DAS Developers' Hub
  url: https://developers.dasintel.io/docs/api
