REST-API Getting started

Wie ist die REST API aufgebaut?

Die pressmind® API ist in sogenannte Controller aufgeteilt. Jeder dieser Controller ist für die Verarbeitung von Daten eines bestimmten Bereiches zuständig. Derzeit stellt pressmind® ca. 5 verschiedene Controller zur Verfügung. Der wohl am häufigsten gebrauchte Controller ist der s.g. Text Controller, mit diesem ist es u.a. möglich sich direkt die Produktdaten aus pressmind® ausgeben zulassen. Dazu ist nicht viel mehr zu tun als eine spezielle URL zu formen und sich über diese die Daten abzurufen. Die pressmind® API liefert auf jede Anfrage entweder eine JSON Ausgabe oder im Fehlerfall einen HTTP Code zurück. Für einen möglichst einfachen Start haben wir im Download Bereich einen PHP basierten Beispiel Client bereitgestellt. Auf den folgenden Seiten finden Sie alle verfügbaren Controller und dessen Parameter. Zögern Sie auch nicht uns zu kontaktieren. Wir stehen Ihnen gern mit Rat und Tat zur Seite.

Endpunkt:

Der Endpunkt ist abhängig von dem installierten pressmind® System. Den korrekten Endpunkt entnehmen Sie bitte der pressmind® Software unter: Menü => Einstellungen => Client

https://{ENDPOINT}/rest/

Bei Systemen im Produktiv-Einsatz empfiehlt sich die Spezifierung der API-Version. Somit werden Änderungen an der API ausgeschlossen und kompatibilitäts Probleme vermieden.

https://{ENDPOINT}/{VERSION}/rest/

Die Versionsnummer ist identisch mit der des pressmind® Clients. Bitte beachten das veraltete Versionen nur zeitlich begrenzt zur Verfügung stehen. Beta Versionen sind nicht für den Produktivbetrieb bestimmt.

Repräsentation: JSON

Das Antwort-Format ist JSON (JavaScript Object Notation). Dies ist ein einfaches maschinenlesbares Format zum Datenaustausch. Weitere Informationen zu JSON finden Sie unter json.org. Beispiel Antwort:

[
	{
		"somekey": "somevalue"
	}
]

Syntax

https://{ENDPOINT}/{VERSION}/rest/{CONTROLLER}/api/{KEY}/{PARAMETER1}/{VALUE1}/

Wenn nicht anderes angegeben erfolgen die Aufrufe via HTTP GET Header.

Autorisierung

Via HTTP Digest. Grundsätzlich kann sich jeder in der pressmind® definierte Frontend User anmelden. Bei erfolgreicher Anmeldung werden die Benutzer Informationen/Berechtigungen mittels der Methode currentUser:index bereitgestellt. Im Fehlerfall HTTP Header 401 Unauthorized.

Hello World Beispiel

Ein einfaches Beispiel: Der Aufruf der HelloWorld::helloPressmind Methode. Tauschen Sie in der URI den Wert "pressmind" gegen "world" aus. .

https://{ENDPOINT}/rest/HelloWorld/api/{Key}/hello/pressmind

Ausgabebeispiel:

[
	{
		"you": "hello pressmind"
	},
	{
		 "pressmind": "hello dude"
	}
 ]

CategoryTree Controller

Merkmale und Kategorien werden in pressmind® in sogenannten "Trees" abgelegt. Jedes Merkmal kann somit beliebig tief veschachtelt werden. Der CategoryTree Controller gibt alle vorhandenen Trees, wahlweise mit oder ohne Elemente der Baumstruktur aus.

Aufruf

Ausgabe aller CategoryTrees

https://{URI}/rest/CategoryTree/api/{Key}

Ausgabe aller CategoryTrees, samt aller Elemente

https://{URI}/rest/CategoryTree/api/{Key}/withData/1

Parameter

Siehe auch CategoryTreeIndex

Contact Controller

In pressmind® gespeicherte Adressen werden über der Contact Controller bereitgestellt.

Aufruf

Alle Kontakte

https://{URI}/rest/Contact/api/{Key}

Aufruf eine Kontaktes mit bekannter ID:

https://{URI}/rest/Contact/api/{Key}/id/{ID}/

Aufruf aller Kontakte aus der Schweiz

https://{URI}/rest/Contact/api/{Key}/country/CH

Aufruf aller männlichen Kontakte aus der Schweiz

https://{URI}/rest/Contact/api/{Key}/country/CH/gender/male

Parameter

CountryCode Controller

Country Code Tabelle nach ISO-3166-1-alpha-2. Der Controller erlaubt die Auflösung von Code zu Name oder gibt die vollständige Liste zurück. Siehe auch https://www.iso.org/iso-3166-country-codes.html

Aufbaubeispiele

Ausgabe der kompletten Länderliste

https://{URI}/rest/CountryCode/api/{Key}

Auflösung von Country Code "CH" zu Name "Switzerland":

https://{URI}/rest/CountryCode/api/{Key}/code/CH

Parameter

CategoryTreeIndex Controller

Dieser Service dient speziell zur Entwicklung von Suchmasken. Es werden nur valide und zugeordnete Merkmale der Trees ausgegeben, damit wird es ermöglicht das z.B. eine Selectbox nur Elemente anzeigt zu der auch Produkte aktiv vorhanden sind.

Aufruf

Beispiel 1: Gibt einen definierten Tree nur mit Elemente aus welche mindestens einem Medienobjekt zugewiesen sind.

http://{URI}/rest/CategoryTreeIndex/api/{Key}/id_category_tree/{ID}

Beispiel 2: Wie Beispiel 1 nur mit ergänzter Sichtbarkeitsstufe "public"

http://{URI}/rest/CategoryTreeIndex/api/{Key}/id_category_tree/{ID}/visibilty/30

Parameter

CurrentUser Controller

Der CurrrentUser Controller gibt alle Informationen rund um den eingeloggten Frontend-Benutzer zurück. Frontend Benutzer sind innerhalb von pressmind® berechtigt sich an der API anzumelden. Über ein individuelles Rechtemanagement ist es somit möglich auf ein vorgefertigtes Usermanagement zurück zugreifen.

Aufruf

https://{URI}/rest/Text/api/{Key}/

Parameter

Document Controller

Dokumentbasierte Medienobjekte sind Bilder bzw. Dateien welche in pressmind® hinterlegt sind. Der Document Controller bietet die Möglichkeit diese über verschiedene Schalter zu filtern. Der Syntax ist dabei annähernd der gleiche wie der des Text Controllers.

Aufrufbeispiele:

Aufruf eines Medienobjektes:

https://{URI}/rest/Document/api/{Key}/id/{ID}

Aufruf aller Medienobjekte eines bestimmten Objekttypen:

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/

Aufruf aller Medienobjekte mit der Sichtbarkeit "public":

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility/30

Aufruf aller Medienobjekte mit der Sichtbarkeit "public" unter Berücksichtigung des Gültigkeitzeitraums:

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30

Aufruf aller Medienobjekte einer bestimmten Kategorie mit der aktuellen Sichtbarkeitsstufe "public":

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30/category/{CATEGORY_ID}

Aufruf aller Medienobjekte welche Kategorie1 und Kategorie2 entsprechen

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30/category/{CATEGORY_ID1,CATEGORY_ID2}

Volltextsuche:

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/q/{KEYWORD}

Volltextsuche in spezifischem Pool:

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/q/{KEYWORD}/id_pool/{ID_POOL}

Ausgabe aller Medienobjekte welche in einem bestimmten Zeitraum geändert wurden:

https://{URI}/rest/Document/api/{Key}/objectType/{OBJECTTYPE_ID}/modified_date_from/{Y-m-d h:m:i}/modified_date_to/{Y-m-d h:m:i}

Parameter

DocumentsGlobal Controller

https://api.pressmind.net/x.x.xxx/rest/DocumentsGlobal/api/meinApiKey

Folgende Funktionen können aufgerufen werden:

ErpGroup Controller

Artikel werden in pressmind zu logischen Verkaufsgruppen zusammengestellt. Diese Verkaufsgruppen bestehen aus Artikeln, Artikelvarianten, Bildern, Preisen und je nach Konfiguration unterschiedlichen Zubehörlisten. Ein Artikel kann zudem innerhalb einer Verkaufsgruppe spezifische Attribute annehmen. Innerhalb einer Verkaufsgruppe kann ein Artikel als Master markiert sein. Einer Produktbeschreibung können mehrere Verkaufsgruppen zugewiesen sein. Der ErpGroup Controller gibt diese Informationen in strukturierter Form aus.

Aufruf

Aufruf aller ERP Gruppen

https://{URI}/rest/ErpGroup/api/{KEY}/

Aufruf einer bestimmten ERP Gruppe

https://{URI}/rest/ErpGroup/api/{KEY}/id/{ID}

Parameter

ErpArticle Controller

https://api.pressmind.net/x.x.xxx/rest/Aggregator/api/meinApiKey/

Führt eine ERP Artikel Suche aus. Folgende Parameter sind möglich:

ErpAttribute Controller

https://api.pressmind.net/x.x.xxx/rest/ErpAttribute/api/meinApiKey

Startet eine Suche in ERP Attributen. Folgende Parameter sind möglich:

Image Controller

Der Image Controller dient zum vereinfachten Zugriff auf dokumentorientierte Medienobjekte. Er wurde speziell dazu entwickelt, Bilder mit allen zur Veröffentlichung erforderlichen Informationen auszugeben. Dazu zählt: Bildunterschrift, Copyrighthinweis, Lizenztyp sowie die Sichtbarkeitsstufe innerhalb von pressmind®. Zudem wird auch die URL des Bildes mitgeliefert.

Aufruf

Aufruf eines eines Bildes, das Bild wird mit einer Größe von 100x100 Pixel ausgegeben

https://{URI}/rest/Image/api/{Key}/id/{ID}/w/100/h/100

Aufruf eines eines Bildes, das Bild wird mit einer Größe von 100x100 Pixel ausgegeben, zusätzlich wird ein Filter angewandt

https://{URI}/rest/Image/api/{Key}/id/{ID}/w/100/h/100/f/toaster

Parameter

ObjectType Controller

Jedes pressmind® System basiert auf individuell für den Kunden konfigurierten Datenmodellen. Jede Entinität innerhalb des dynamischen Datenmodells wird als "Objekttyp" bezeichnet. Dieser Controller gibt alle Informationen des Medienobjekttypen aus. (Ein Medienobjekttyp kann entweder für ein dokument- oder textbasiertes Medienobjekt definiert werden).

Aufruf

http://{URI}/rest/ObjectType/api/{Key}/

Parameter

Ping Controller

Der Ping Controller ist zu einfachen Testzwecken gedacht.

Aufruf

https://{URI}/rest/Ping/api/{Key}/ping/helloworld

Parameter

Text Controller

Der Text Controller dient zur Bereitstellung von textbasierten Medienobjekten. Auf dieser Seiten finden Sie die aktuelle Dokumentation des Controllers. Dieser Controller ist häufig der Ausgangspunkt für die auf der pressmind® API basierenden Projekte. Er listet und filtert alle textbasierten Produktbeschreibungen auf und kann als vollständige Suchmaschne genutzt werden.

Aufrufbeispiele:

Aufruf eines Medienobjektes:

https://{URI}/rest/Text/api/{Key}/id/{ID}

Aufruf aller Medienobjekte eines bestimmten Objekttypen:

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/

Aufruf aller Medienobjekte mit der Sichtbarkeit "public":

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility/30

Aufruf aller Medienobjekte mit der Sichtbarkeit "public" unter Berücksichtigung des Gültigkeitzeitraums:

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30

Aufruf aller Medienobjekte einer bestimmten Kategorie mit der aktuellen Sichtbarkeitsstufe "public":

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30/category/{CATEGORY_ID}

Aufruf aller Medienobjekte welche Kategorie1 und Kategorie2 entsprechen

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/visibility_current/30/category/{CATEGORY_ID1,CATEGORY_ID2}

Volltextsuche:

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/q/{KEYWORD}

Volltextsuche in spezifischem Pool:

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/q/{KEYWORD}/id_pool/{ID_POOL}

Ausgabe aller Medienobjekte welche in einem bestimmten Zeitraum geändert wurden:

https://{URI}/rest/Text/api/{Key}/objectType/{OBJECTTYPE_ID}/modified_date_from/{Y-m-d h:m:i}/modified_date_to/{Y-m-d h:m:i}

Parameter

Touristik Modul

Folgende Parameter sind nur bei aktiviertem Touristikmodul nutzbar:

PHP Rest Client

Features:

• direkter Zugriff auf die pressmind® REST API via GET, POST, PUT und DELETE
• Unterstützung der pressmind® Controller Logik
• GZIP Unterstützung
• SSL Unterstützung
• basiert auf der PHP Extension mod_curl
• kompatibel mit PHP > 5.3

Objekt Liste:

Pressmind ruft via POST das definierte Script auf. z.B.:

http://domain.de/cms/pressmind.php

Als POST Parameter werden die Werte numItems und startIndex mit übermittelt. Mit diesen übermittelten Werten können Sie auf Ihrer Seite ein Paging realisieren um ein schnelles Anzeigen von vielen Objekte zu gewährleisten (analog zu MySQL "limit")

Als Antwort wird folgendes JSON Objekt erwartet:

{
    "filter": [{
        "fields": [ // defines the search filter
            {
                "name": "Code", // display name
                "key": "code", // submitted POST name of the field. Do not use numItems or startIndex (reserved for paging)
                "type": "input", // possible types = input | dropdown
                "values": [] // if type=dropdown set values here
            },
            {
                "name": "Name",
                "key": "name",
                "type": "input",
                "values": []
            },
            {
                "name": "Destination",
                "key": "destination",
                "type": "dropdown",
                "values": [ // the dropdown list
                    {
                        "text": "Deutschland", // display name
                        "value": "DE" // submitted value
                    },
                    {
                        "text": "Holland",
                        "value": "nl"
                    }
                ]
            }
        ]
    }],
    "count": 10, // count of search result, see paging
    "items": [{
            "id": 1,
            "link": "http://api.domain.de/detail.php?id=1", // link to your detail objects description -> see below
            "editor_link": "http://cms.domain.de/editor.php?id=1", // [optional] link to your cms editor, displays a button
            "values": [{
                    "key": "code", // same key as above
                    "value": "ABCD"
                },
                {
                    "key": "name",
                    "value": "Produkt 1"
                },
                {
                    "key": "destination",
                    "value": "Deutschland"
                }
            ]
        },
        {
            "id": 2,
            "link": "http://api.domain.de/detail.php?id=2",
            "editor_link": "http://cms.domain.de/editor.php?id=2",
            "values": [{
                    "key": "code",
                    "value": "DCBA"
                },
                {
                    "key": "name",
                    "value": "Produkt 2"
                },
                {
                    "key": "destination",
                    "value": "Holland"
                }
            ]
        }
    ]
}
	

Detaillierte Objektbeschreibung

Nach dem der pressmind® Benutzer einen Datensatz aus der Objekte Liste aufgerufen hat, wird anhand der definierten URL die detallierte Objektbeschreibung aufgerufen und in pressmind® importiert. Das Objekt ist ab diesem Zeitpunkt mit pressmind® vernüpft. pressmind® überprüft in regelmäßigen Abständen ob sich der Datensatz geändert hat und führt ggf. einen Reimport aus

Folgende Ausgabe wird als Objektbeschreibung erwartet:

{
    "id": 12345, // unique id
    "code": "ABCD", // [optional] code or article no
    "name": "Produktname 1",
    "checksum": "acbd18db4cc2f85cedef654fccc4a4d8", // pressmind will reimport the object if this token is changend
    "values": [{
            "id": 1,
            "name": "headline", // your field name
            "value": "Produktname 1
 Lorem Ipsum", // value htmlencoded, if type = image, value = array -> see below
            "type": "text", // plaintext | text | image | table
            "pressmind_target": "Headline:Default" // the target field in pressmind. Syntax: [FieldVariable]:[SectionName]
        },
        {
            "id": 2,
            "name": "subline",
            "value": "Ipsum Lorem",
            "type": "text",
            "pressmind_target": "Subline:Default"
        },
        {
            "id": 3,
            "name": "details",
            "value": "Lorem Ipsum
Lorem Ipsum...",
            "type": "text",
            "pressmind_target": "details:Default"
        },
        {
            "id": 4,
            "name": "details",
            "value": "
            	<table>
                	<tr>
                		<td > .... </td>
                	</tr>
                </table>
            ",
            "type": "table",
            "pressmind_target": "PriceTable:Default"
        },
        {
            "id": 5,
            "name": "pictures",
            "value": [{
                    "checksum": xxx, // pressmind will reimport this image if this value is changed
                    "url": "http://yourdomain.de/hires_image1.jpg",
                    "title": "",
                    "copyright": "",
                    "caption": ""
                },
                {
                    "checksum": yyy,
                    "url": "http://yourdomain.de/hires_image2.jpg",
                    "title": "",
                    "copyright": "",
                    "caption": ""
                }
            ],
            "type": "image",
            "pressmind_target": "Bilder:Default"
        }
    ]
}

Bitte nehmen Sie vor der Implementierung unbedingt Kontakt mit uns auf.
support@pressmind.de