REST-Webservices
webPDF stellt seine Schnittstellen (Interface) als REST-Webservices gemäß der "Java Specification Request (JSR) 311" (https://jsr311.java.net/) zur Verfügung. Die Bereitstellung basiert auf den Web-Standards und dem HTTP-Protokoll.
Die Funktionen von webPDF werden als REST (Representational State Transfer) Ressourcen bereitgestellt und können über einen Uniform Resource Identifier (URI) angesprochen werden. Die Darstellung der Ressourcen erfolgt in JSON (http://www.json.org/).
Der webPDF-Server stellt die REST-Webservices auf Basis JAX-RS 2.0 (https://jax-rs-spec.java.net/) und der Jersey-Referenzimplementierung (https://jersey.java.net/) bereit.
Die verschieden URI der Webservices sind über die HTTP-Methoden PUT, GET, POST und DELETE ausführbar.
Als dies zusammen bildet die webPDF REST API, die allgemein unter "REST Webservice API" und technische unter "API {REST}" beschrieben wird.
Dokumentation als OpenAPI
Die Dokumentation wird automatisiert als OpenAPI bereitgestellt. Zur automatisierten Verarbeitung oder Import in Entwicklerwerkzeuge oder Frameworks kann diese auch direkt als JSON oder YAML-Struktur abgerufen werden:
JSON: http://localhost:8080/webPDF/rest/openapi.json
YAML: http://localhost:8080/webPDF/rest/openapi.yaml
URI der Webservices
Alle URI haben die gemeinsame Basis-URL
/webPDF/rest
Danach folgt das URL-Segment für den jeweiligen Webservice, gefolgt von weiteren Segmenten, die Webservice-spezifisch sind. Nachfolgend eine Übersicht über die bereitgestellten Webservices (siehe "Webservices") mit ihren Basis-URI:
| Webservice | URI | API Dokumentation |
|---|---|---|
| Converter | /webPDF/rest/converter/... | API {REST} |
| Signature | /webPDF/rest/signature/... | API {REST} |
| Pdfa | /webPDF/rest/pdfa/... | API {REST} |
| Toolbox | /webPDF/rest/toolbox/... | API {REST} |
| URLConverter | /webPDF/rest/urlconverter/... | API {REST} |
| OCR | /webPDF/rest/ocr/... | API {REST} |
| Barcode | /webPDF/rest/barcode/... | API {REST} |
Darüber hinaus existieren zwei URI, die für die Verwaltung der Dokumente (Webservice "documents") und der Anmeldung (Webservice "authentication") dienen.
Beispiele für Webservice-Aufrufe
Konvertiert das Dokument mit der ID "2f32abfc05594f42bb89128a4052817d" über den Webservice "Converter" in ein PDF-Dokument
POST http://localhost:8080/webPDF/rest/converter/2f32abfc05594f42bb89128a4052817d
Liest die Informationen über den aktuell angemeldeten Benutzer aus.
GET http://localhost:8080/webPDF/rest/authentication/user/info
Liest die Liste der Dateien aus, die aktuell für die Session auf dem Server gespeichert sind.
GET http://localhost:8080/webPDF/rest/documents/list
Eine detaillierte Nutzung der REST API (mit curl-Beispielen) ist unter "REST Webservice API" beschrieben.
Parameter zur Steuerung der Webservices
Bei den REST-Webservices werden die Parameter in JSON-Strukturen übergeben, die im "Request Body" der Anfrage (z.B. POST oder GET) enthalten sind.
Wenn Sie einen Endpunkt der REST-Webservices aufrufen, dann setzen Sie den Header Content-Type auf den Wert application/json.