diff --git a/.gitignore b/.gitignore
index b2d6de30624f651a6c584d4faefafceac6302be1..51d2e0f9105c3a182f45b7aaafb6aee53ca00ced 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,7 +2,7 @@
/node_modules
# Production
-/build
+/docs/_build
# Generated files
.docusaurus
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e3628c0c2cbd8fb55fdb319b7eba7efaf50a4757..65f249862c4660bcf258035aa37740be2401ec67 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -6,12 +6,12 @@ stages:
docs-build:
stage: build
- image: python:latest
+ image: python:3.10
script:
- pip install -U jupyter-book
- jupyter-book clean docs
+ - jupyter-book toc from-project docs > docs/_toc.yml
- jupyter-book build docs
- - ls
artifacts:
paths:
- docs/_build/
diff --git a/docs/guides/web-api/categories-api.md b/docs/guides/web-api/categories-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..d5b0e753fc62f2bd8a59a9d955692bad7ec2d401
--- /dev/null
+++ b/docs/guides/web-api/categories-api.md
@@ -0,0 +1,81 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 3
+---
+
+# /categories
+
+This API provides the user information on the basic categories by the which the information in the HKG is grouped, and the total number of records found for each of this categories, respectively.
+
+### Method
+
+GET
+
+### Search Params
+
+None
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/categories](https://search.unhide.helmholtz-metadaten.de/api/categories)
+
+### Response Model
+
+```
+[
+ {
+ id: string,
+ text: string,
+ count: number
+ }
+]
+```
+
+where, `id` is the identifier of the category, `text` is the name of the category to be displayed on the UI, and `count` presents the total number of records available for the given category
+
+#### Example
+
+```
+[
+ {
+ id: "datasets",
+ text: "Datasets",
+ count: 411935,
+ },
+ {
+ id: "software",
+ text: "Software",
+ count: 3521,
+ },
+ {
+ id: "documents",
+ text: "Documents",
+ count: 1679342,
+ },
+ {
+ id: "instruments",
+ text: "Instruments",
+ count: 0,
+ },
+ {
+ id: "experts",
+ text: "Experts",
+ count: 229601,
+ },
+ {
+ id: "institutions",
+ text: "Institutions",
+ count: 64472,
+ },
+ {
+ id: "trainings",
+ text: "Trainings",
+ count: 667,
+ },
+ {
+ id: "projects",
+ text: "Projects",
+ count: 0,
+ },
+ ]
+```
diff --git a/docs/guides/web-api/hello-api.md b/docs/guides/web-api/hello-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..03e7a6ae145fd363426bfc3f3222d0da91d29577
--- /dev/null
+++ b/docs/guides/web-api/hello-api.md
@@ -0,0 +1,36 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 2
+---
+
+# /hello
+
+This API is currently used to test that the server is up and available. It will eventually be pointing to this documentation.
+
+### Method
+
+GET
+
+### Search Params
+
+None
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/hello](https://search.unhide.helmholtz-metadaten.de/api/hello)
+
+### Response Model
+
+```
+{
+ "message": string
+}
+```
+
+#### Example
+
+```
+{
+ "message": "Hello from Next.js!"
+}
+```
diff --git a/docs/guides/web-api/introduction.md b/docs/guides/web-api/introduction.md
index 40dac4a2355f9db22860f89ebd47e5b64e62f5b2..e02a5d340b741f686be8c6ac71606d614a2c9cbe 100644
--- a/docs/guides/web-api/introduction.md
+++ b/docs/guides/web-api/introduction.md
@@ -4,3 +4,5 @@ sidebar_position: 1
---
# Introduction
+
+The web APIs related to UnHIDE are made available at [https://search.unhide.helmholtz-metadaten.de/api/[endpoint]](https://search.unhide.helmholtz-metadaten.de/api/hello). There are currently four APIs defined, the details of which are covered in the following sections
diff --git a/docs/guides/web-api/json-ld-source-api.md b/docs/guides/web-api/json-ld-source-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..3eb789ff031b83b436206f92c4ed2c31a51d3b88
--- /dev/null
+++ b/docs/guides/web-api/json-ld-source-api.md
@@ -0,0 +1,66 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 5
+---
+
+# /source
+
+This API provides the user the JSON-LD object containing information of a record for the given ID.
+
+### Method
+
+GET
+
+### Search Params
+
+`id` - the identifier value of the record of interest
+
+#### Examples
+
+`id=e6be83435b277f34cab97adbefbe7b03` Or
+`id=https%3A%2F%2Fror.org%2F04t3en479`
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/source?id=](https://search.unhide.helmholtz-metadaten.de/api/source?id=)
+
+### Response Model
+
+```
+{
+ @type: string,
+ ...
+}
+```
+
+where, `@type` is the type of the metadata record identified,
+additionally, all information that is avaliable in the record, depending on its type is sent across as part of the response object
+
+#### Examples
+
+For `id=https%3A%2F%2Forcid.org%2F0000-0001-9827-4429`
+
+```
+{
+ "@id": "https://orcid.org/0000-0001-9827-4429",
+ "@type": "Person",
+ "affiliation": {
+ "@id": "https://ror.org/03v76x132",
+ "@type": "Organization",
+ "name": "Yale University"
+ },
+ "familyName": "Liang",
+ "givenName": "Yu",
+ "name": "Yu Liang"
+}
+```
+
+For `id=https%3A%2F%2Fror.org%2F04t3en479`
+
+```
+{
+ "@id": "https://ror.org/04t3en479",
+ "@type": "Organization",
+ "name": "Karlsruhe Institute of Technology"
+}
+```
diff --git a/docs/guides/web-api/search-api.md b/docs/guides/web-api/search-api.md
new file mode 100644
index 0000000000000000000000000000000000000000..a8cc9ec23fa0d6d78a4848822bcbec0b7b4fca7b
--- /dev/null
+++ b/docs/guides/web-api/search-api.md
@@ -0,0 +1,234 @@
+---
+displayed_sidebar: guidesSidebar
+sidebar_position: 3
+---
+
+# /search
+
+This API provides the user the search results for a given search query.
+
+### Method
+
+GET
+
+### Search Params
+
+`searchText` - term that is being searched for (string)
+
+`start` - row of record to start fetching from (optional; number; defaults to 0)
+
+`rows` - number of rows to be fetched in a call (optional; number; defaults to 10)
+
+`documentType` - the identifier of the category of interest (optional; string; see [/categories](/docs/guides/web-api/categories-api#example) for possible values)
+
+`includeFacet` - flag to indicate whether dynamic filters are required for a given search (optional; boolean)
+
+`facetType` - identifier of the dynamic filter (optional, works with `facetName`; string; see [data model](/docs//about/data-model/index.md#filters) for possible values)
+
+`facetName` - value of the dynamic filter chosen (optional, works with `facetType`; string; this depends on the possible values made available for this filter type)
+
+### URL
+
+[https://search.unhide.helmholtz-metadaten.de/api/search?[searchParams]](https://search.unhide.helmholtz-metadaten.de/api/search?)
+
+### Response Model
+
+```
+{
+ "records": [
+ {
+ "id": string,
+ "type": string,
+ "keys": [ string ],
+ ...
+ "recordConfig": {
+ "index_id": string,
+ "_version_": string,
+ "indexed_ts": timestamp string
+ }
+ },
+ ],
+ "totalCount": number,
+ "categoryCounts": {
+ {categoryid}: count,
+ ...
+ },
+ "filters": [
+ {
+ "filterName": string,
+ "itemName": string,
+ "itemCount": number
+ },
+ ...
+ ]
+}
+```
+
+where,
+
+`records` is a list of records fetched based on the search params. Each record object can have different key-value pairs depending upon the category of the data under interest.
+
+`totalCount` is the total number of records available for the given search
+
+`categoryCounts` presents the total number of records available for the given category and search,
+
+`filters` provides a list of filter objects if the `facetType` and `facetName` are supplied when `includeFacet` is set to true for a given search call.
+
+#### Example
+
+For the following search params:
+
+`searchText` - "Forschungszentrum Jülich"
+
+`documentType` - "documents"
+
+`facetType` - "txt_contributor"
+
+`facetName` - "Angst, Manuel"
+
+`facetType` - "txt_contributor"
+
+`facetName` - "Zorn, Reiner"
+
+`facetType` - "txt_publisher"
+
+`facetName` - "Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"
+
+`facetType` - "txt_keywords"
+
+`facetName` - "info:eu-repo/classification/ddc/600"
+
+```
+{
+ "records": [
+ {
+ "id": "https://juser.fz-juelich.de/record/22096",
+ "type": "DigitalDocument",
+ "txt_contributor": ["Angst, Manuel", "Brückel, Thomas", "Roth, G", "Zorn, Reiner"],
+ "txt_creator": ["Brückel, Thomas"],
+ "txt_identifier": [
+ "https://juser.fz-juelich.de/record/22096",
+ "https://juser.fz-juelich.de/search?p=id:%22PreJuSER-22096%22"
+ ],
+ "txt_keywords": [
+ "info:eu-repo/classification/ddc/530",
+ "info:eu-repo/classification/ddc/600"
+ ],
+ "txt_license": ["info:eu-repo/semantics/openAccess"],
+ "name": "01: Introduction: Neutron Scattering in Contemporary Research",
+ "txt_provider": [
+ "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14"
+ ],
+ "txt_publisher": ["Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"],
+ "txt_sameAs": ["[info:eu-repo, semantics, altIdentifier, hdl, 2128, 4740]"],
+ "keys": [
+ "id",
+ "type",
+ "txt_contributor",
+ "txt_creator",
+ "txt_identifier",
+ "txt_keywords",
+ "txt_license",
+ "name",
+ "txt_provider",
+ "txt_publisher",
+ "txt_sameAs"
+ ],
+ "recordConfig": {
+ "index_id": "3915592a-f9cd-4932-a048-7aa1019d3a67",
+ "_version_": "1778867342397145088",
+ "indexed_ts": "2023-10-04T22:54:56.738Z"
+ }
+ },
+ {
+ "id": "https://juser.fz-juelich.de/record/19548",
+ "type": "DigitalDocument",
+ "txt_contributor": ["Angst, Manuel", "Brückel, Thomas", "Roth, G", "Zorn, Reiner"],
+ "txt_creator": ["Frielinghaus, Henrich"],
+ "txt_identifier": [
+ "https://juser.fz-juelich.de/record/19548",
+ "https://juser.fz-juelich.de/search?p=id:%22PreJuSER-19548%22"
+ ],
+ "txt_keywords": [
+ "info:eu-repo/classification/ddc/530",
+ "info:eu-repo/classification/ddc/600"
+ ],
+ "txt_license": ["info:eu-repo/semantics/openAccess"],
+ "name": "05: Nanostructures Investigated by Small Angle Neutron Scattering",
+ "txt_provider": [
+ "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14"
+ ],
+ "txt_publisher": ["Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster"],
+ "txt_sameAs": ["[info:eu-repo, semantics, altIdentifier, isbn, 978-3-89336-789-4]"],
+ "keys": [
+ "id",
+ "type",
+ "txt_contributor",
+ "txt_creator",
+ "txt_identifier",
+ "txt_keywords",
+ "txt_license",
+ "name",
+ "txt_provider",
+ "txt_publisher",
+ "txt_sameAs"
+ ],
+ "recordConfig": {
+ "index_id": "4e71f085-59f4-4dc0-8ac5-4f07a2c8af15",
+ "_version_": "1778856255287197696",
+ "indexed_ts": "2023-10-04T19:58:43.246Z"
+ }
+ }
+ ],
+ "totalCount": 2,
+ "categoryCounts": {
+ "experts": 0,
+ "documents": 2,
+ "datasets": 0,
+ "institutions": 0,
+ "trainings": 0,
+ "projects": 0,
+ "software": 0,
+ "instruments": 0
+ },
+ "filters": [
+ {
+ "filterName": "txt_keywords",
+ "itemName": "info:eu-repo/classification/ddc/530",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_keywords",
+ "itemName": "info:eu-repo/classification/ddc/600",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_contributor",
+ "itemName": "Angst, Manuel",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_contributor",
+ "itemName": "Brückel, Thomas",
+ "itemCount": 2
+ },
+ { "filterName": "txt_contributor", "itemName": "Roth, G", "itemCount": 2 },
+ { "filterName": "txt_contributor", "itemName": "Zorn, Reiner", "itemCount": 2 },
+ {
+ "filterName": "txt_license",
+ "itemName": "info:eu-repo/semantics/openAccess",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_provider",
+ "itemName": "JCNS Neutron Lab Course / Th. Brückel, D. Richter, G. Roth, R. Zorn (Eds.) ; Schriften des Forschungszentrums Jülich / Reihe Schlüsseltechnologien / Key Technologies, Vol. 39, Forschungszentrum Jülich GmbH, 2012; 978-3-89336-789-4<br/>JCNS Neutron Laborator Course, Jülich/München, Germany, 2012-09-03 - 2012-09-14",
+ "itemCount": 2
+ },
+ {
+ "filterName": "txt_publisher",
+ "itemName": "Forschungszentrum Jülich GmbH, JCNS / RWTH Aachen / Univ. Münster",
+ "itemCount": 2
+ }
+ ]
+}
+```
diff --git a/index.md b/docs/index.md
similarity index 100%
rename from index.md
rename to docs/index.md
diff --git a/sidebars.ts b/sidebars.ts
index 6f6a93a3e33c745bad5b824f4a000d2d68086a1f..9d853bdfe40a5ff17ebe46d21a61f00e5b12e554 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -36,7 +36,13 @@ const sidebars: SidebarsConfig = {
type: "generated-index",
},
collapsed: true,
- items: ["guides/web-api/introduction"],
+ items: [
+ "guides/web-api/introduction",
+ "guides/web-api/hello-api",
+ "guides/web-api/categories-api",
+ "guides/web-api/search-api",
+ "guides/web-api/json-ld-source-api",
+ ],
},
{
type: "category",