Skip to content
GEO Knowledge Hub

Publishing a Knowledge Resource

A Resource is the smallest publishable unit in the GEO Knowledge Hub. The flow is the same whether the Resource is published standalone or attached to a Knowledge Package. The only difference is how it is published: When associated with a Package, it must be published via the Package; otherwise, it can be published standalone.

The next steps show you can use the Rest API to publish a Knowledge Resource:

  1. Create a draft

    Section titled “Create a draft”

    Sends an empty-ish record body. The server responds with the new draft id under id, and a links object with all the URLs you need for the subsequent steps (file upload, metadata update, publish).

    POST /api/records HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "access": { "record": "public", "files": "public" },
      "files": { "enabled": true },
      "metadata": {
        "title": "Processing Script — NDVI Calculation",
        "publication_date": "2024-01-15",
        "resource_type": { "id": "software" },
        "creators": [
          {
            "person_or_org": {
              "type": "personal",
              "family_name": "Smith",
              "given_name": "Jane"
            }
          }
        ]
      }
    }

    Response: 201 Created. Capture id from the response body for the next steps.

  2. Upload files

    Section titled “Upload files”

    Each file follows a three-step pattern: init → upload → commit. Users initialize the file, upload content and commit. This process must be done for every file you want to upload.

    2a. Initialize

    Section titled “2a. Initialize”
    POST /api/records/{id}/draft/files HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    [
      { "key": "ndvi_script.py" }
    ]

    Response: 201 Created.

    2b. Upload content

    Section titled “2b. Upload content”
    PUT /api/records/{id}/draft/files/ndvi_script.py/content HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/octet-stream
    

    <binary file data>

    Response: 200 OK.

    2c. Commit

    Section titled “2c. Commit”
    POST /api/records/{id}/draft/files/ndvi_script.py/commit HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    Response: 200 OK. The file is now part of the draft.

  3. Update metadata

    Section titled “Update metadata”

    PUT replaces the metadata block. This operation only updates metadata fields sent in the request body. If you are updating few resource fields, there is no need to send the entire record body.

    PUT /api/records/{id}/draft HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>
    Content-Type: application/json
    

    {
      "access": { "record": "public", "files": "public" },
      "files": { "enabled": true },
      "metadata": {
        "title": "Processing Script — NDVI Calculation",
        "description": "Python script to calculate NDVI from Sentinel-2 data.",
        "rights": [{ "id": "mit" }],
        "subjects": [
          { "subject": "NDVI" },
          { "subject": "Sentinel-2" }
        ],
        "languages": [{ "id": "eng" }],
        "publication_date": "2024-01-15",
        "resource_type": { "id": "software" },
        "creators": [
          {
            "person_or_org": {
              "type": "personal",
              "family_name": "Smith",
              "given_name": "Jane"
            }
          }
        ]
      }
    }

    Response: 200 OK.

  4. Publish

    Section titled “Publish”

    Publishing a standalone Resource mints a DOI and makes it public.

    POST /api/records/{id}/draft/actions/publish HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    Response: 202 Accepted.

  5. (Optional) Create a new version

    Section titled “(Optional) Create a new version”

    After publication, files are immutable. To update them, open a new version. The response is a fresh draft with an incremented versions.index that you can edit and publish independently from the original.

    POST /api/records/{id}/versions HTTP/1.1
    Host: gkhub.earthobservations.org
    Authorization: Bearer <token>

    Response: 201 Created. From here, repeat steps 2 → 4 against the new draft.