REST API Endpoint Reference

REST API Endpoint Reference#

The udala.tablon package extends Plone 6's core REST API with a dedicated router at the /@tablon path. This endpoint provides dynamic, language-agnostic access to the Electronic Notice Board, utilizing the Shared UID architecture.

1. Create Document (POST /@tablon)#

Creates a new DocumentoTablon and its associated AcreditedFile children. It orchestrates automatic translation generation if Plone App Multilingual is installed.

Request Body#

The JSON payload uses a dynamic translations dictionary, allowing it to scale to any number of languages or monolingual setups without rigid _eu/_es suffixes.

{
  "record_number": "2024/001",
  "date_start": "2024-03-01T00:00:00",
  "date_end": "2024-03-31T23:59:59",
  "origin": "external",
  "translations": {
    "eu": {
        "origin_department": "Kultura Saila",
        "origin_details": "Udaletxea",
        "description": "Kultur egitarauaren diru-laguntzak",
        "publication_url": "https://www.donostia.eus"
    },
    "es": {
        "origin_department": "Departamento de Cultura",
        "origin_details": "Ayuntamiento",
        "description": "Subvenciones para programas culturales",
        "publication_url": "https://www.donostia.eus/es"
    }
  },
  "documents": [
    {
      "language": null,
      "filename": "deialdia_convocatoria.pdf",
      "contents": "JVBERi0xLjMKJc...",
      "titles": {
          "eu": "Deialdia",
          "es": "Convocatoria"
      }
    }
  ]
}

Responses#

  • 201 Created: Contains the generated Shared UUID and the absolute physical URLs to the new Plone items. The returned keys (for example, url_eu, url_es, url_en) will dynamically match the language block provided in the payload's translations dictionary.

  • 400 Bad Request: Validation errors (for example, missing fields in a specific language block).

  • 500 Internal Server Error: No Tablon container found in the system.

2. Get Document (GET /@tablon/{shared_uid})#

Retrieves the serialized JSON of the document corresponding to the shared_uid.

Headers#

  • Accept-Language: The API natively parses HTTP language headers (for example, eu,en;q=0.9) to filter the exact translation block needed. If no specific language is requested or found, it dynamically falls back to the portal's default language.

Response#

Returns the standard Plone REST API JSON serialization, with the added translatable fields dynamically injected based on the available translations in the Zope Annotation dictionary.

{
    "@id": "http://localhost:8080/Plone/@tablon/b2c3d4e5f6g7h8i9j0k1",
    "uuid": "b2c3d4e5f6g7h8i9j0k1",
    "record_number": "2024/001",
    "date_start": "2024-03-01T00:00:00Z",
    "date_end": "2024-03-31T23:59:59Z",
    "origin": "external",
    "translations": {
        "eu": {
            "origin_department": "Kultura Saila",
            "origin_details": "Udaletxea",
            "description": "Kultur egitarauaren diru-laguntzak",
            "publication_url": "https://www.donostia.eus"
        },
        "es": {
            "origin_department": "Departamento de Cultura",
            "origin_details": "Ayuntamiento",
            "description": "Subvenciones para programas culturales",
            "publication_url": "https://www.donostia.eus/es"
        }
    },
    "documents": [
        {
            "@id": "http://localhost:8080/Plone/@tablon/b2c3d4e5f6g7h8i9j0k1/a1b2c3d4e5",
            "uuid": "a1b2c3d4e5",
            "titles": {
                "eu": "Deialdia",
                "es": "Convocatoria"
            },
            "izenpe_urls": {
                "eu": "http://accreditation.service/cert",
                "es": "http://accreditation.service/cert"
            },
            "izenpe_contents": {
                "eu": "base64...",
                "es": "base64..."
            },
            "filename": "deialdia_convocatoria.pdf",
            "contents": "JVBERi..."
        }
    ]
}

3. Get Expired Documents (GET /@tablon-expired)#

Retrieves a list of documents that have expired on a specific date.

Query Parameters#

  • date: (Optional) An ISO-formatted date string (for example, YYYY-MM-DD). Defaults to the current date if omitted.

Response#

Returns an array of serialized DocumentoTablon JSON objects.

4. Get File (GET /@tablon/{shared_uid}/{file_shared_uid})#

Retrieves the serialized JSON of a specific file. Useful for verifying the izenpe_url (the external accreditation certificate URL).

5. Delete Document (DELETE /@tablon/{shared_uid})#

Deletes the document and all its associated files and translations from the Plone database. Also purges the Shared UID entry from the annotation storage mapping.

Response#

  • 204 No Content: Successful deletion.

  • 404 Not Found: The document or translation could not be located.

6. Trigger Manual Accreditation (GET /@tablon/{shared_uid}/{file_shared_uid}/get_external_accreditation)#

An asynchronous trigger endpoint used to force a retry of the external accreditation connection for a specific file.

Response#

{"status": "ok"}
Contents