API schema endpoints

[sd109]

It looks like integrating aide with our existing code to generate a proper OpenAPI schema is going to be a little difficult (more trait bound issues which I think stem from our custom models::Response implementation). I will continue looking into this but in the mean time, this PR adds two endpoints which return simple JSON schema to at least provide some form of live documentation.

[sd109]

Generated request schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "RequestData",
  "description": "Request data for operations",
  "type": "object",
  "required": [
    "bucket",
    "dtype",
    "object",
    "source"
  ],
  "properties": {
    "bucket": {
      "description": "S3 bucket containing the object",
      "type": "string",
      "minLength": 1
    },
    "dtype": {
      "description": "Data type",
      "allOf": [
        {
          "$ref": "#/definitions/DType"
        }
      ]
    },
    "object": {
      "description": "S3 object containing the data",
      "type": "string",
      "minLength": 1
    },
    "offset": {
      "description": "Offset in bytes of the numerical data within the object",
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 0.0
    },
    "order": {
      "description": "Order of the multi-dimensional array",
      "anyOf": [
        {
          "$ref": "#/definitions/Order"
        },
        {
          "type": "null"
        }
      ]
    },
    "selection": {
      "description": "Subset of the data to operate on",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/definitions/Slice"
      },
      "minItems": 1
    },
    "shape": {
      "description": "Shape of the multi-dimensional array",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer",
        "format": "uint",
        "minimum": 0.0
      },
      "minItems": 1
    },
    "size": {
      "description": "Size in bytes of the numerical data from the offset",
      "type": [
        "integer",
        "null"
      ],
      "format": "uint",
      "minimum": 1.0
    },
    "source": {
      "description": "URL of the S3-compatible object store",
      "type": "string",
      "format": "uri"
    }
  },
  "additionalProperties": false,
  "definitions": {
    "DType": {
      "description": "Supported numerical data types",
      "oneOf": [
        {
          "description": "[i32]",
          "type": "string",
          "enum": [
            "int32"
          ]
        },
        {
          "description": "[i64]",
          "type": "string",
          "enum": [
            "int64"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint32"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint64"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float32"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float64"
          ]
        }
      ]
    },
    "Order": {
      "description": "Array ordering\n\nDefines an ordering for multi-dimensional arrays.",
      "oneOf": [
        {
          "description": "Row-major (C) ordering",
          "type": "string",
          "enum": [
            "C"
          ]
        },
        {
          "description": "Column-major (Fortran) ordering",
          "type": "string",
          "enum": [
            "F"
          ]
        }
      ]
    },
    "Slice": {
      "description": "A slice of a single dimension of an array\n\nThe API uses NumPy slice (i.e. [start, end, stride]) semantics where:\n\nWhen start or end is negative: * positive_start = start + length * positive_end = end + length Start and end are clamped: * positive_start = min(positive_start, 0) * positive_end + max(positive_end, length) When the stride is positive: * positive_start <= i < positive_end When the stride is negative: * positive_end <= i < positive_start",
      "type": "object",
      "required": [
        "end",
        "start",
        "stride"
      ],
      "properties": {
        "end": {
          "description": "End of the slice",
          "type": "integer",
          "format": "int"
        },
        "start": {
          "description": "Start of the slice",
          "type": "integer",
          "format": "int"
        },
        "stride": {
          "description": "Stride size",
          "type": "integer",
          "format": "int"
        }
      },
      "additionalProperties": false
    }
  }
}

Generated response schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Response",
  "description": "Response containing the result of a computation and associated metadata.",
  "type": "object",
  "required": [
    "body",
    "dtype",
    "shape"
  ],
  "properties": {
    "body": {
      "description": "Raw response data as bytes. May represent a scalar or multi-dimensional array.",
      "type": "array",
      "items": {
        "type": "integer",
        "format": "uint8",
        "minimum": 0.0
      }
    },
    "dtype": {
      "description": "Data type of the response",
      "allOf": [
        {
          "$ref": "#/definitions/DType"
        }
      ]
    },
    "shape": {
      "description": "Shape of the response",
      "type": "array",
      "items": {
        "type": "integer",
        "format": "uint",
        "minimum": 0.0
      }
    }
  },
  "definitions": {
    "DType": {
      "description": "Supported numerical data types",
      "oneOf": [
        {
          "description": "[i32]",
          "type": "string",
          "enum": [
            "int32"
          ]
        },
        {
          "description": "[i64]",
          "type": "string",
          "enum": [
            "int64"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint32"
          ]
        },
        {
          "description": "[u64]",
          "type": "string",
          "enum": [
            "uint64"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float32"
          ]
        },
        {
          "description": "[f64]",
          "type": "string",
          "enum": [
            "float64"
          ]
        }
      ]
    }
  }
}

[markgoddard]

Seems like a reasonable compromise.