{
  "openapi": "3.0.3",
  "info": {
    "version": "1.4.4-dev",
    "title": "DSpace Statistics API",
    "description": "A [Falcon-based](https://falcon.readthedocs.io/) web application to make DSpace's item, community, and collection statistics available via a simple REST API. This Swagger interface is powered by [falcon-swagger-ui](https://github.com/rdidyk/falcon-swagger-ui).",
    "license": {
      "name": "GPLv3.0",
      "url": "https://www.gnu.org/licenses/gpl-3.0.en.html"
    }
  },
  "paths": {
    "/item/{item_uuid}": {
      "get": {
        "summary": "Statistics for a specific item",
        "operationId": "getItem",
        "tags": [
          "item"
        ],
        "parameters": [
          {
            "name": "item_uuid",
            "in": "path",
            "required": true,
            "description": "The UUID of the item to retrieve",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "9596aeff-0b90-47d3-9fec-02d578920507"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "404": {
            "description": "Item not found"
          }
        }
      }
    },
    "/items": {
      "get": {
        "summary": "Get statistics for all items",
        "operationId": "getItems",
        "tags": [
          "items"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many items to return at once (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 100,
              "default": 100,
              "example": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page of results to start on (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      },
      "post": {
        "summary": "Get statistics for a list of items with an optional date range",
        "operationId": "postItems",
        "tags": [
          "items"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 100
                  },
                  "page": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0,
                    "default": 0
                  },
                  "dateFrom": {
                    "type": "string",
                    "format": "date"
                  },
                  "dateTo": {
                    "type": "string",
                    "format": "date"
                  },
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "example": {
                  "limit": 100,
                  "page": 0,
                  "dateFrom": "2020-01-01T00:00:00Z",
                  "dateTo": "2020-12-31T00:00:00Z",
                  "items": [
                    "f44cf173-2344-4eb2-8f00-ee55df32c76f",
                    "2324aa41-e9de-4a2b-bc36-16241464683e",
                    "8542f9da-9ce1-4614-abf4-f2e3fdb4b305",
                    "0fe573e7-042a-4240-a4d9-753b61233908"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "currentPage": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "limit": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "totalPages": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "statistics": {
                      "$ref": "#/components/schemas/ListOfElements"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/community/{community_uuid}": {
      "get": {
        "summary": "Statistics for a specific community",
        "operationId": "getCommunity",
        "tags": [
          "community"
        ],
        "parameters": [
          {
            "name": "community_uuid",
            "in": "path",
            "required": true,
            "description": "The UUID of the community to retrieve",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "bde7139c-d321-46bb-aef6-ae70799e5edb"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "404": {
            "description": "Community not found"
          }
        }
      }
    },
    "/communities": {
      "get": {
        "summary": "Get statistics for all communities",
        "operationId": "getCommunities",
        "tags": [
          "communities"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many communities to return at once (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 100,
              "default": 100,
              "example": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Zero-based page of results to start on (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of communities",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      },
      "post": {
        "summary": "Get statistics for a list of communities with an optional date range",
        "operationId": "postCommunities",
        "tags": [
          "communities"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 100
                  },
                  "page": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0,
                    "default": 0
                  },
                  "dateFrom": {
                    "type": "string",
                    "format": "date"
                  },
                  "dateTo": {
                    "type": "string",
                    "format": "date"
                  },
                  "communities": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "example": {
                  "limit": 100,
                  "page": 0,
                  "dateFrom": "2020-01-01T00:00:00Z",
                  "dateTo": "2020-12-31T00:00:00Z",
                  "communities": [
                    "bde7139c-d321-46bb-aef6-ae70799e5edb",
                    "8a8aeed1-077e-4360-bdf8-a5f3020193b1",
                    "47d0498a-203c-407d-afb8-1d44bf29badc",
                    "d3fe99a9-e27d-4035-9339-084c93228c82"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "currentPage": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "limit": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "totalPages": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "statistics": {
                      "$ref": "#/components/schemas/ListOfElements"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/collection/{collection_uuid}": {
      "get": {
        "summary": "Statistics for a specific collection",
        "operationId": "getCollection",
        "tags": [
          "collection"
        ],
        "parameters": [
          {
            "name": "collection_uuid",
            "in": "path",
            "required": true,
            "description": "The UUID of the collection to retrieve",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "49dc95d8-bf2f-4e68-b30f-41ea266c37ae"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "404": {
            "description": "Collection not found"
          }
        }
      }
    },
    "/collections": {
      "get": {
        "summary": "Get statistics for all collections",
        "operationId": "getCollections",
        "tags": [
          "collections"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "How many collections to return at once (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 1,
              "maximum": 100,
              "default": 100,
              "example": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Zero-based page of results to start on (optional)",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "minimum": 0,
              "default": 0,
              "example": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paged array of collections",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SingleElementResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      },
      "post": {
        "summary": "Get statistics for a list of collections with an optional date range",
        "operationId": "postCollections",
        "tags": [
          "collections"
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 100
                  },
                  "page": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0,
                    "default": 0
                  },
                  "dateFrom": {
                    "type": "string",
                    "format": "date"
                  },
                  "dateTo": {
                    "type": "string",
                    "format": "date"
                  },
                  "collections": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                },
                "example": {
                  "limit": 100,
                  "page": 0,
                  "dateFrom": "2020-01-01T00:00:00Z",
                  "dateTo": "2020-12-31T00:00:00Z",
                  "collections": [
                    "5eeef6cf-b91b-42d0-9549-ea61bc8a758f",
                    "6aac3269-b4a9-4924-a24d-9e6ee2b410d2",
                    "551698dd-cd2b-4327-948e-54b5eb6deda5",
                    "39358713-bbaf-4149-a453-e2b18c09fd5d"
                  ]
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Expected response to a valid request",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "currentPage": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "limit": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "totalPages": {
                      "type": "integer",
                      "format": "int32"
                    },
                    "statistics": {
                      "$ref": "#/components/schemas/ListOfElements"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/status": {
      "get": {
        "summary": "Get API status",
        "operationId": "getStatus",
        "tags": [
          "status"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string",
                      "example": "1.4.0-dev"
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method Not Allowed"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SingleElementResponse": {
        "type": "object",
        "required": [
          "id",
          "views",
          "downloads"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "views": {
            "type": "integer",
            "example": 450
          },
          "downloads": {
            "type": "integer",
            "example": 1337
          }
        }
      },
      "ListOfElements": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/SingleElementResponse"
        }
      }
    }
  }
}