First API version

mcapi.yml

+swagger: "2.0"
+
+info:
+  description: >
+    Simple rest API for access to massive point clouds repositories.
+    Point clouds are spatially indexed using the coordinates of their 
+    bounding boxes. Each model has an associated data (raw point data or in laz format).
+    
+    
+    This version only supports a level-of-detaIl (data in a single block). Future
+    versions will organize data using a hierarchy of LODs (e.g., using an octree).
+
+  version: "0.1"
+  title: Massive Clouds
+  contact:
+    email: ajrueda@ujaen.es
+
+basePath: /massiveclouds
+tags:
+- name: "workspaces"
+  description: "Workspaces management"
+- name: "models"
+  description: "Point cloud models management"
+- name: "data"
+  description: "Access to model data"
+schemes:
+- http
+
+# API specification ----------------------------
+paths:
+
+  /workspace:
+    get:
+      tags:
+      - "workspaces"
+      summary: Lists the registered workspaces
+      produces:
+      - application/json
+      responses:
+        200:
+          description: Successful operation
+          schema:
+            type: array
+            items: 
+              $ref: '#/definitions/Workspace'
+    post:
+      tags:
+      - "workspaces"
+      summary: Registers a new workspace
+      consumes:
+      - application/json
+      parameters:
+      - in: body
+        name: body
+        description: Workspace to be added
+        required: true
+        schema:
+          $ref: '#/definitions/Workspace'
+      responses:
+        201:
+          description: Workspace created successfully
+        409:
+          description: Workspace already existing
+
+  /workspace/{workspaceName}:
+    get:
+      tags:
+      - "workspaces"
+      summary: Returns workspace info.
+      produces:
+      - application/json
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string      
+      responses:
+        200:
+          description: Successful operation
+          schema:
+            $ref: '#/definitions/Workspace'
+        404:
+          description: Unknown project name
+
+  /workspace/{workspaceName}/model:
+    get:
+      tags:
+      - "models"
+      summary: >
+        Returns a list of models in the workspace
+      produces:
+      - application/json
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string
+      - in: query
+        name: west
+        description: West side of the box to filter models
+        type: number
+      - in: query
+        name: south
+        description: South side of the box to filter models
+        type: number
+      - in: query
+        name: east
+        description: East side of the box to filter models
+        type: number
+      - in: query
+        name: north
+        description: North side of the box to filter models
+        type: number
+        
+      responses:
+        200:
+          description: Successful operation
+          schema:
+            type: array
+            items:
+              $ref: '#/definitions/Model'
+        404:
+          description: Unknown workspace
+
+    post:
+      tags:
+      - "models"
+      summary: Creates a model in the workspace.
+      consumes:
+      - application/json
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string      
+      - in: body
+        name: body
+        description: Model to be added
+        required: true
+        schema:
+          $ref: '#/definitions/Workspace'
+      responses:
+        201:
+          description: Model created successfully
+        409:
+          description: Model already existing in workspace
+
+  /workspace/{workspaceName}/model/{modelName}:
+    get:
+      tags:
+      - "models"
+      summary: Returns the given model
+      produces:
+      - application/json
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string      
+      - in: path
+        name: modelName
+        description: Model name
+        required: true
+        type: string      
+
+      responses:
+        200:
+          description: Successful operation
+          schema:
+            $ref: '#/definitions/Model'
+        404:
+          description: Unknown workspace or model
+
+  /workspace/{workspaceName}/model/{modelName}/data:
+    get:
+      tags:
+      - "data"
+      summary: Returns the given model associated data in raw or laz format (to decide)
+      produces:
+      - application/octet-stream
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string      
+      - in: path
+        name: modelName
+        description: Model name
+        required: true
+        schema:
+          type: string
+          format: binary
+
+    post:
+      tags:
+      - "data"
+      summary: Uploads a model in raw or laz format (to decide)
+      consumes:
+      - application/octet-stream
+      parameters:
+      - in: path
+        name: workspaceName
+        description: Workspace name
+        required: true
+        type: string      
+      - in: path
+        name: modelName
+        description: Model name
+        required: true
+        schema:
+          type: string
+          format: binary
+      - in: body
+        name: dataToUpload
+        description: model data to upload
+        required: true
+        schema:
+          type: string
+          format: binary
+
+      responses:
+        200:
+          description: Successful operation
+        404:
+          description: Unknown workspace or model
+        409:
+          description: Model data already has associated data
+
+# Model definitions ----------------------------
+definitions:
+
+  Workspace:
+      type: object
+      description: Workspace containing one or more georreferenced point clouds
+      properties:
+        name:
+          type: string
+          description: Name of the workspace (avoid spaces if possible)
+        type:
+          type: string
+          description: Description of the workspace and its purpose
+    
+      required:
+      - name
+      example:
+        name: CHJaen
+        description: Scanned models of cultural heritage sites in the province of Jaén
+
+  Model:
+    type: object
+    description: Georreferenced model (normally a point cloud).
+    properties:
+      name:
+        type: string
+        description: Name of the model.
+      description:
+        type: string
+        description: Description and purpose of the model.
+      dateAdquisition:
+        type: string
+        format: "date-time"
+        description: Date and time of aquisition of the model.
+      bbox: 
+        $ref: '#/definitions/GeorefBox'
+        description: Georreferenced bounding box of the model.
+    required:
+    - name
+    - bbox
+    example:
+      name: CastilloSCatalina
+      description: |
+        Model of Castillo de Santa Catalina (Jaén). 
+        Captured with Leica RTC360 laser scanner
+      date: "2019-05-03T12:10:00Z"
+      bbox:
+        east: 37.768673
+        north: 3.804588
+        west: 37.767032
+        south: -3.798777
+
+  # LOD:
+  #   type: object
+  #   descrition: Representation of a model with a given level of detail
+  #   properties:
+  #     bbox:
+  #       $ref: '#/definitions/GeomBox'
+  #     description: > 
+  #       Bounding box of the LOD. Should use semi-normalized cartesian coordinates 
+  #       to avoid precision errors (avoid UTM or degrees).
+  #     dataId:
+  #       type: integer
+  #       description: Id to access data
+
+  GeorefBox:
+    type: object
+    description: Box defined by latitude and longitude
+    properties:
+      west:
+        type: number
+        description: West coordinate
+      north:
+        type: number
+        description: South coordinate
+      east:
+        type: number
+        description: East coordinate
+      south:
+        type: number
+        description: North coordinate
+    required:
+    - west
+    - north
+    - east
+    - south
+
+  # GeomBox:
+  #   type: object
+  #   description: Box defined in 3D space
+  #   properties:
+  #     minX:
+  #       type: number
+  #       description: Minimal X coordinate
+  #     minY:
+  #       type: number
+  #       description: Minimal Y coordinate
+  #     minZ:
+  #       type: number
+  #       description: Minimal Z coordinate
+  #     maxX:
+  #       type: number
+  #       description: Maximum X coordinate
+  #     maxY:
+  #       type: number
+  #       description: Maximum Y coordinate
+  #     maxZ:
+  #       type: number
+  #       description: Minimal Z coordinate
+
+  #   required:
+  #   - minX
+  #   - minY
+  #   - minZ
+  #   - maxX
+  #   - maxY
+  #   - maxZ