Resources

This documentation page will present the API available in the GEO Knowledge Hub to access and manage Knowledge Resources.

tip

Before you use this API, we recommend you be familiar with the structure of a Knowledge Resource document in the GEO Knowledge Hub.

Drafts

Used for interacting with unpublished or edited draft resources.

Authentication required

All requests to the draft-related Rest API endpoints require authentication.

Create draft

POST /api/records

Parameters

Name	Type	Location	Description
`access`	object	body	Access options for the record.
`files`	object	body	Files options (see below) for the record.
`metadata`	object	body	Metadata of the record.

Files Options

Name	Type	Location	Description
`enabled`	boolean	body	Required. Should (and can) files be attached to this record or not.
`default_preview`	string	body	Filename of file to be previewed by default.
`order`	array	body	Array of filename strings in display order.

Request

POST /api/records HTTP/1.1
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public"
  },
  "files": {
    "enabled": true
  },
  "metadata": {
    "creators": [
      {
        "person_or_org": {
          "family_name": "Brown",
          "given_name": "Troy",
          "type": "personal"
        }
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "Entity One"
          }
        ]
      }
    ],
    "publication_date": "2020-06-01",
    "resource_type": { "id": "image-photo" },
    "title": "A Romans story",
  }
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": true
  },
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      {
        "person_or_org": {
          "family_name": "Brown",
          "given_name": "Troy",
          "type": "personal"
        }
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
          "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Get draft

GET /api/records/{id}/draft

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records/{id}/draft HTTP/1.1 
Accept: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "public",
    "files": "public",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": true
  },
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "A Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Update draft

PUT /api/records/{id}/draft

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`access`	object	body	Access options for the record.
`files`	object	body	Files options for the record.
`metadata`	object	body	Metadata of the record.

Request

PUT /api/records/{id}/draft HTTP/1.1
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted"
  },
  "files": {
    "enabled": false
  },
  "metadata": {
    "creators": [
      {
        "person_or_org": {
          "family_name": "Brown",
          "given_name": "Troy",
          "type": "personal"
        }
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "Entity One"
          }
        ]
      }
    ],
    "publication_date": "2020-06-01",
    "resource_type": { "id": "image-photo" },
    "title": "An Updated Romans story"
  }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": false
  },
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": false,
    "is_latest_draft": true
  }
}

Publish draft

POST /api/records/{id}/draft/actions/publish

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

POST /api/records/{id}/draft/actions/publish HTTP/1.1

Response

HTTP/1.1 202 ACCEPTED
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": false
  },
  "id": "{id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Edit published resource (Create a draft from a published resource)

POST /api/records/{id}/draft

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

POST /api/records/{id}/draft HTTP/1.1

Response

HTTP/1.1 201 CREATED
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": false
  },
  "id": "{id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Delete/discard draft

DELETE /api/records/{id}/draft

Deleting a draft for an unpublished resource will remove the draft and associated files from the system.

Deleting a draft for a published resource will remove the draft but not the published resource.

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

DELETE /api/records/{id}/draft HTTP/1.1

Response

HTTP/1.1 204 No Content

Draft files

Used to manage draft files.

Authentication required

All requests to the draft-related Rest API endpoints require authentication.

List draft files

GET /api/records/{id}/draft/files

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

GET /api/records/{id}/draft/files HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "default_preview": null,
  "enabled": true,
  "entries": [],
  "links": {
    "self": "/api/records/{id}/draft/files"
  },
  "order": []
}

Start draft file upload(s)

POST /api/records/{id}/draft/files

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`<top-level>`	array	body	Array of objects describing the file uploads to be initialized.
`[].key`	string	body	Name of the file to be uploaded.

Request

POST /api/records/{id}/draft/files HTTP/1.1
Content-Type: application/json

[
  {"key": "figure.png"},
  {"key": "article.pdf"},
  {"key": "data.zip"}
]

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "enabled": true,
  "default_preview": null,
  "order": [],
  "entries": [
    {
      "key": "figure.png",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/figure.png/content",
        "self": "/api/records/{id}/draft/files/figure.png",
        "commit": "/api/records/{id}/draft/files/figure.png/commit"
      },
    },
        {
      "key": "article.pdf",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/article.pdf/content",
        "self": "/api/records/{id}/draft/files/article.pdf",
        "commit": "/api/records/{id}/draft/files/article.pdf/commit"
      },
    },
    {
      "key": "data.zip",
      "updated": "2020-11-27 11:17:11.002624",
      "created": "2020-11-27 11:17:10.998919",
      "metadata": null,
      "status": "pending",
      "links": {
        "content": "/api/records/{id}/draft/files/data.zip/content",
        "self": "/api/records/{id}/draft/files/data.zip",
        "commit": "/api/records/{id}/draft/files/data.zip/commit"
      },
    }
  ],
  "links": {
    "self": "/api/records/{id}/draft/files"
  },
}

Upload draft file content

PUT /api/records/{id}/draft/files/{filename}/content

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`filename`	string	path	Name of the file.
`content-type`	string	header	Should always be `application/octet-stream`.
`content-length`	integer	header	Size of the content in bytes (optional).
`<content>`	bytes	body	The raw bytes of the file content to be uploaded.

Request

PUT /api/records/{id}/draft/files/{filename}/content HTTP/1.1
Content-Type: application/octet-stream

<...file binary data...>

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:17:11.002624",
  "created": "2020-11-27 11:17:10.998919",
  "metadata": null,
    "status": "pending",
    "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Code sample

curl \
  --request PUT \
  --header "Content-Type: application/octet-stream" \
  https://127.0.0.1:5000//api/records/{id}/draft/files/{filename}/content \
  --upload-file /path/to/file

Complete draft file upload

POST /api/records/{id}/draft/files/{filename}/commit

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`filename`	string	path	Name of the file.

Request

POST /api/records/{id}/draft/files/{filename}/commit HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:26:04.607831",
  "created": "2020-11-27 11:17:10.998919",
  "checksum": "md5:6ef4267f0e710357c895627e931f16cd",
  "mimetype": "image/png",
  "size": 89364.0,
  "status": "completed",
  "metadata": null,
  "file_id": "2151fa94-6dc3-4965-8df9-ec73ceb9175c",
  "version_id": "57ad8c66-b934-49c9-a46f-38bf5aa0374f",
  "bucket_id": "90b5b318-114a-4b87-bc9d-0d018b9363d3",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Get draft file metadata

GET /api/records/{id}/draft/files/{filename}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`filename`	string	path	Name of the file.

Request

GET /api/records/{id}/draft/files/{filename} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "updated": "2020-11-27 11:26:04.607831",
  "created": "2020-11-27 11:17:10.998919",
  "checksum": "md5:6ef4267f0e710357c895627e931f16cd",
  "mimetype": "image/png",
  "size": 89364.0,
  "status": "completed",
  "metadata": {
    "width": 960,
    "height": 640
  },
  "file_id": "2151fa94-6dc3-4965-8df9-ec73ceb9175c",
  "version_id": "57ad8c66-b934-49c9-a46f-38bf5aa0374f",
  "bucket_id": "90b5b318-114a-4b87-bc9d-0d018b9363d3",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/draft/files/{filename}/content",
    "self": "/api/records/{id}/draft/files/{filename}",
    "commit": "/api/records/{id}/draft/files/{filename}/commit"
  },
}

Download draft file

GET /api/records/{id}/draft/files/{filename}/content

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`filename`	string	path	Name of a file

Request

GET /api/records/{id}/draft/files/{filename}/content HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline
Content-Length: 76122
Content-MD5: 71449104d017a6056ac1a5fb58754975
Content-Type: image/pdf
Date: Thu, 26 Nov 2020 18:35:33 GMT
ETag: "md5:71449104d017a6056ac1a5fb58754975"
Last-Modified: Thu, 26 Nov 2020 14:30:06 GMT

<...file binary data...>

Delete draft file

DELETE /api/records/{id}/draft/files/{filename}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`
`filename`	string	path	Name of the file.

Request

DELETE /api/records/{id}/draft/files/{filename} HTTP/1.1

Response

HTTP/1.1 204 No Content

Published resources

Used for interacting with published resources.

Get resource

GET /api/records/{id}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records/{id} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": true
  },
  "id": "{id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      {
        "person_or_org": {
          "given_name": "Troy",
          "type": "personal",
          "name": "Brown, Troy",
          "family_name": "Brown"
        }
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 1,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Search resources

Parameters

Name	Type	Location	Description
`q`	string	query	Search query used to filter results based on ElasticSearch's query string syntax.
`bbox`	string	query	Bounding box search query (You need to define two points, `Top Left` and `Bottom Right`, with the format 'longitude,latitude,longitude,latitude').
`sort`	string	query	Sort search results.
`size`	integer	query	Specify number of items in the results page (default: 10).
`page`	integer	query	Specify the page of results.
`allversions`	boolean	query	Specify if all versions should be included.
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

Each hit looks like a resource above.

Resource files

Used for interacting with files of a published resource.

List resource files

GET /api/records/{id}/files

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`accept`	string	header	- `application/json` (default)

Request

GET /api/records/{id}/files HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "enabled": true,
  "default_preview": "article.pdf",
  "order": [],
  "entries": [
    {
      "key": "article.pdf",
      "created": "2020-11-26 14:30:53.911912",
            "updated": "2020-11-26 14:30:53.920544",
      "checksum": "md5:71449104d017a6056ac1a5fb58754975",
      "mimetype": "application/pdf",
      "size": 76122,
      "status": "completed",
      "metadata": {...},
      "file_id": "...",
      "version_id": "...",
      "bucket_id": "...",
      "storage_class": "S",
      "links": {
        "content": "/api/records/{id}/files/article.pdf/content",
        "self": "/api/records/{id}/files/article.pdf"
      }
    }
  ]
  "links": {...},
}

Get resource file metadata

GET /api/records/{id}/files/{filename}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`filename`	string	path	Name of a file
`accept`	string	header	- `application/json` (default)

Request

GET /api/records/{id}/files/{filename} HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "{filename}",
  "created": "2020-11-26 14:30:53.911912",
  "updated": "2020-11-26 14:30:53.920544",
  "checksum": "md5:71449104d017a6056ac1a5fb58754975",
  "mimetype": "application/pdf",
  "size": 76122,
  "status": "completed",
  "metadata": {...},
  "file_id": "...",
  "version_id": "...",
  "bucket_id": "...",
  "storage_class": "S",
  "links": {
    "content": "/api/records/{id}/files/{filename}/content",
    "self": "/api/records/{id}/files/{filename}"
  }
}

Download resource file

GET /api/records/{id}/files/{filename}/content

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`filename`	string	path	Name of a file

Request

GET /api/records/{id}/files/{filename}/content HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Disposition: inline
Content-Length: 76122
Content-MD5: 71449104d017a6056ac1a5fb58754975
Content-Type: image/pdf
Date: Thu, 26 Nov 2020 18:35:33 GMT
ETag: "md5:71449104d017a6056ac1a5fb58754975"
Last-Modified: Thu, 26 Nov 2020 14:30:06 GMT

<...file binary data...>

Versions

Used for interacting with resource versions.

Create a new version

POST /api/records/{id}/versions

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

POST /api/records/{id}/versions HTTP/1.1

Response

HTTP/1.1 201 OK
Content-Type: application/json


{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    }
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": true
  },
  "id": "{new-id}",
  "is_published": false,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/uploads/{id}",
    "publish": "{scheme+hostname}/api/records/{id}/draft/actions/publish",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}/draft",
    "files": "{scheme+hostname}/api/records/{id}/draft/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "name": "Brown, Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 2,
    "is_latest": false,
    "is_latest_draft": true
  }
}

info

After creating the new draft, you can publish it.

note

Notice that a new draft is returned with publication_date and version removed (as those are typically replaced in a new version).

The versions.index is also incremented. The {parent-id} connects the different versions together.

Get all versions

GET /api/records/{id}/versions

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `4d0ns-ntd89`

Request

GET /api/records/{id}/versions HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {...},
  "sortBy": "version",
  "links": {...}
}

Get latest version

Given a resource, it returns its latest version.

GET /api/records/{id}/versions/latest

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of a record, e.g. `cbc2k-q9x58`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records/{id}/versions/latest HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access": {
    "record": "restricted",
    "files": "restricted",
    "embargo": {
      "reason": null,
      "active": false
    },
    "status": "restricted"
  },
  "created": "2020-11-27 10:52:23.945755",
  "expires_at": "2020-11-27 10:52:23.945868",
  "files": {
    "enabled": true,
    "order": []
  },
  "id": "{latest-version-id}",
  "is_published": true,
  "links": {
    "latest": "{scheme+hostname}/api/records/{id}/versions/latest",
    "versions": "{scheme+hostname}/api/records/{id}/versions",
    "self_html": "{scheme+hostname}/records/{id}",
    "latest_html": "{scheme+hostname}/records/{id}/latest",
    "self": "{scheme+hostname}/api/records/{id}",
    "files": "{scheme+hostname}/api/records/{id}/files",
    "access_links": "{scheme+hostname}/api/records/{id}/access/links"
  },
  "metadata": {
    "resource_type": {
      "id": "image-photo",
      "title": {
        "en": "Photo"
      }
    },
    "title": "An Updated Romans story",
    "publication_date": "2020-06-01",
    "creators": [
      "person_or_org": {
        "family_name": "Brown",
        "given_name": "Troy",
        "type": "personal"
      },
      {
        "person_or_org": {
          "family_name": "Collins",
          "given_name": "Thomas",
          "identifiers": [
            {"scheme": "orcid", "identifier": "0000-0002-1825-0097"}
          ],
          "name": "Collins, Thomas",
          "type": "personal"
        },
        "affiliations": [
          {
            "id": "01ggx4157",
            "name": "European Organization for Nuclear Research"
          }
        ]
      }
    ],
  },
  "parent": {
    "id": "{parent-id}",
    "access": {
      "owned_by": [
        {
            "user": {user-id}
        }
      ],
      "links": []
    }
  },
  "pids": {},
  "revision_id": 3,
  "updated": "2020-11-27 10:52:23.969244",
  "versions": {
    "index": 2,
    "is_latest": true,
    "is_latest_draft": true
  }
}

Access links

Access links are URLs that can be shared with others to give them access and permissions to a resource/draft.

Create an access link

POST /api/records/{id}/access/links

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`
`expires_at`	string	body	Date time string. When the link expires.
`permission`	string	body	Required. Action that can be undertaken with the link (`view`, `preview` or `edit`).

Request

POST /api/records/{id}/access/links HTTP/1.1
Content-Type: application/json

{
  "permission": "view"
}

Response

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "permission": "view",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": null
}

Get an access link

GET /api/records/{id}/access/links/{link-id}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`link-id`	string	path	Identifier of the link, e.g. `3d3320ea-0755-4d93-a76e-e2f2fc655d2a`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permission": "view",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": null
}

Update an access link

PATCH /api/records/{id}/access/links/{link-id}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`link-id`	string	path	Identifier of the link, e.g. `3d3320ea-0755-4d93-a76e-e2f2fc655d2a`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`
`expires_at`	string	body	Date time string. When the link expires.
`permission`	string	body	Required. Action that can be undertaken with the link.

Request

PATCH /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

{
  "permission": "edit",
  "expires_at": "2121-03-25T21:06:29.563235"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "permission": "edit",
  "created_at": "2021-03-25T21:06:29.563235",
  "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjNkMzMyMGVhLTA3NTUtNGQ5My1hNzZlLWUyZjJmYzY1NWQyYSIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzZhYTk3OTczMzgwMjkyNTJiM2MwZDBjNjliMTVkYSJ9.dBqk7YzIZ7kwG4oijNgH1VU-cjQmBiQlMQKMoB2y-YjVWmgnZetFAESsqRP6VpGTtaKdftrtob1PVZJF4YGpfg",
  "id": "3d3320ea-0755-4d93-a76e-e2f2fc655d2a",
  "expires_at": "2121-03-25T21:06:29.563235"
}

Delete an access link

DELETE /api/records/{id}/access/links/{link-id}

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`link-id`	string	path	Identifier of the link, e.g. `3d3320ea-0755-4d93-a76e-e2f2fc655d2a`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

DELETE /api/records/{id}/access/links/{link-id} HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 204 No Content

List access links

GET /api/records/{id}/access/links

Parameters

Name	Type	Location	Description
`id`	string	path	Identifier of the record, e.g. `cbc2k-q9x58`
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/records/{id}/access/links HTTP/1.1
Content-Type: application/json

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "hits": {
    "hits": [
      {
        "permission": "view",
        "id": "140f69c9-a8a5-41d4-8ae2-3dfbfe0e2796",
        "created_at": "2021-03-25T21:48:03.289198",
        "expires_at": null,
        "token": "eyJhbGciOiJIUzUxMiJ9.eyJpZCI6IjE0MGY2OWM5LWE4YTUtNDFkNC04YWUyLTNkZmJmZTBlMjc5NiIsImRhdGEiOnt9LCJyYW5kb20iOiI2NzE3MmY4MTNkYzhkNGJjZDAwOWFlOTlhOWM3NjU1MSJ9.1O9MwTmt_nfvsCm4qvlkUH0Rpe5bK3hT422A879DJSblOCONsNxPe_feNHrgTV3s6ZA6t6vLziXjhAwgKjHhIQ"
      }
    ],
    "total": 1
  }
}

User resources

Used for interacting with the resources and drafts associated with your user.

Authentication required

All requests to the user-related Rest API endpoints require authentication.

List your draft and published resources

GET /api/user/records

Parameters

Name	Type	Location	Description
`q`	string	query	Search query used to filter results based on ElasticSearch's query string syntax.
`bbox`	string	query	Bounding box search query (You need to define two points, `Top Left` and `Bottom Right`, with the format 'longitude,latitude,longitude,latitude').
`sort`	string	query	Sort search results.
`size`	integer	query	Specify number of items in the results page (default: 10).
`page`	integer	query	Specify the page of results.
`allversions`	boolean	query	Specify if all versions should be included.
`accept`	string	header	- `application/json` (default) - `application/vnd.inveniordm.v1+json`

Request

GET /api/user/records HTTP/1.1

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "aggregations": {...},
  "hits": {...},
  "links": {...},
  "sortBy": ...,
}

tip

Drafts​

Authentication required

Create draft​

Files Options​

Get draft​

Update draft​

Publish draft​

Edit published resource (Create a draft from a published resource)​

Delete/discard draft​

Draft files​

Authentication required

List draft files​

Start draft file upload(s)​

Upload draft file content​

Complete draft file upload​

Get draft file metadata​

Download draft file​

Delete draft file​

Published resources​

Get resource​

Search resources​

Resource files​

List resource files​

Get resource file metadata​

Download resource file​

Versions​

Create a new version​

info

note

Get all versions​

Get latest version​

Access links​

Create an access link​

Get an access link​

Update an access link​

Delete an access link​

List access links​

User resources​

Authentication required

List your draft and published resources​

Drafts

Create draft

Files Options

Get draft

Update draft

Publish draft

Edit published resource (Create a draft from a published resource)

Delete/discard draft

Draft files

List draft files

Start draft file upload(s)

Upload draft file content

Complete draft file upload

Get draft file metadata

Download draft file

Delete draft file

Published resources

Get resource

Search resources

Resource files

List resource files

Get resource file metadata

Download resource file

Versions

Create a new version

Get all versions

Get latest version

Access links

Create an access link

Get an access link

Update an access link

Delete an access link

List access links

User resources

List your draft and published resources