Die API wird zur Integration mit Digital-Asset-Management-Systemen, Nutzerverwaltung und vielem mehr verwendet. Mit dem Showpad-API Explorer können Sie die API ausprobieren und über die Online Platform in den Admin-Einstellungen darauf zugreifen. Dieser Artikel taucht tiefer in die Welt der Showpad-API ein und erläutert die verschiedenen Methoden und Parameter, die Sie verwenden können.
Hinweis: Um direkt auf den API Explorer zuzugreifen, rufen Sie https://{IhreSubdomain}.Showpad.biz/devportal/explorer auf
Hauptmerkmale
Die Showpad-API ist eine RESTful-Client-Server-API. Der Begriff REST wird im Wesentlichen verwendet, um anzuzeigen, dass die API auf den folgenden Prinzipien basiert:
- Senden einer HTTP-Anfrage und Empfangen einer HTTP-Antwort
- Verwendung von HTTP-Verben (GET, POST, PUT...)
- Interpretieren von HTTP-Antwortcodes
- Ressourcen
Anmerkung: Die Basis-URL für die REST-API lautet /API/v{apiVersion}.
Was Sie für den Erfolg benötigen
Sie benötigen Folgendes, um Ihre erste App zu erstellen, die mit der Showpad-REST-API kompatibel ist:
- Den Ultimate-Preisplan von Showpad
- Zugriff auf die Showpad Online Platform
- Grundkenntnisse in REST
- Grundkenntnisse in JSON
Die Konzepte der Großartigkeit
- Universal Resource Location (URL)
- Ressourcen und Ressourcenlinks
- HTTP-Methoden
- Header anfordern
- Medientypen
- Abfrageparameter
- Antwort-Header
- HTTP-Antwortcodes
Universal Resource Location (URL)
Die URL gibt an, auf welche Ressource oder Sammlung von Ressourcenlinks Sie zugreifen möchten. Sie ist wie folgt aufgebaut:
/API/v{apiVersion}/{resource}[/{resourceId}[/{subResource}]][.JSON] |
Nachfolgend einige Beispiele:
- /API/v1/tags.JSON
- /API/v2/assets/12345.JSON
- /API/v2/users/12345/usergroups.JSON
Ressourcen und Ressourcenlinks
Eine Antwort von der Showpad-API basiert auf dem Konzept von Ressourcen und Ressourcenverknüpfungen. Eine Ressource ist die Zentraleinheit innerhalb der Showpad-API. Sie ist gekennzeichnet durch eine ID, einen Typ, eine Reihe von Attributen und eine Reihe von Beziehungen zu anderen Ressourcen.
"response": { "id": "279386a847eb5802fc566cb773916d41", "resourcetype": "Asset", "name": "Showpad One Pager.pdf", .... "tags": { "hrefhttps://demo.showpad.biz/api/v3/assets/279386afc566cb773916d41/tags"RL-0 }, "division": { "id4643adcc1621814e91c489b34bb428edID-1", "hrefhttps://demo.showpad.biz/api/v3/divisions/4643ae91c489b34bb428ed"RL-1 }, |
Ein wichtiges Merkmal der Ressource ist der Typ, der durch das Feld „Ressourcentyp“ identifiziert wird. Jede Ressource hat dieses Feld und es gibt 12 Ressourcentypen, die sowohl auf den Reseller als auch auf die Unternehmens-API verteilt sind.
Ressourcentyp | Verfügbarkeit | Art |
---|---|---|
API-Schlüssel | V1 | Reseller + Unternehmen |
Asset | V1 + | Reseller + Unternehmen |
Kommentar | V1 + | Reseller + Unternehmen |
Inhaltsprofil | V2 + | Unternehmen |
Division | V2 + | Unternehmen |
Divisions-Berechtigung | V2 + | Unternehmen |
Organisation | V1 + | Reseller |
Tablet-Berechtigung | V2 + | Reseller |
Tag | V1 + | Reseller |
Ticket | V1 + | Unternehmen |
Nutzergruppe | V1 + | Unternehmen |
Nutzer | V1 + | Unternehmen |
In einer einfachen REST-API-Konfiguration wird eine HTTP-Anfrage an den Showpad-Server gesendet, der die Anfrage verarbeitet und mit einer HTTP-Antwort antwortet. Die Anforderung selbst enthält eine Reihe von Parametern, die für die Showpad-API wichtig sind. Es werden die folgenden HTTP-Methoden unterstützt, um CRUD-Vorgänge (Create - Datensatz anlegen, Retrieve - Datensatz lesen, Update - Datensatz aktualisieren, Delete - Datensatz löschen) HTTP-Anforderungen zuzuordnen. Darüber hinaus unterstützt die Showpad-API die LINK- UND UNLINK-Methoden zum Erstellen und Löschen von Beziehungen zwischen Ressourcen:
Hinweis: Nutzer haben bei der Verwendung der REST-API keinen Zugriff auf alle Assets.
Methode |
Beschreibung |
---|---|
GET |
Wird verwendet, um Ressourcen aus einer Sammlung von Ressourcenlinks abzurufen. |
POST |
Wird zum Erstellen oder Aktualisieren einer Ressource verwendet. |
PUT |
Wird zum Aktualisieren einer Ressource verwendet. |
DELETE |
Wird zum Entfernen einer Ressource verwendet. |
LINK |
Wird verwendet, um eine Beziehung zwischen Ressourcen herzustellen. |
UNLINK |
Wird verwendet, um eine bestehende Beziehung zwischen Ressourcen zu unterbrechen. |
HEAD |
Wird verwendet, um Ressourcen aus einer Sammlung von Ressourcenlinks abzurufen. |
Header-Parameter sind Parameter, die an den Header der Anforderung angehängt sind. Neben den Standard-Header-Parametern wie Content-Type gibt es einige Header-Parameter, die speziell für die Verwendung in der Showpad-API entwickelt wurden.
Parameter | Art | Version | Beschreibung | |||
---|---|---|---|---|---|---|
SHOWPADAUTHORIZATIONKEY |
|
Alle authentifizierten Anfragen | V1 |
Für jede Anforderung, die eine Authentifizierung erfordert, muss dieser Header festgelegt werden. Er enthält den Showpad-API-Schlüssel. Gilt nur für API V1. |
||
AUTHORIZATION |
|
Alle authentifizierten Anfragen | V2 |
Wird für OAuth2-authentifizierte Anforderungen verwendet. Es enthält das OAuth2-Zugriffstoken im folgenden Format: AUTHORIZATION: Bearer:myObtainedAccessToken Gilt nur für API V2. |
||
LINK |
LINK-, UNLINK- und POST-Anforderungen (Ressourcen erstellen) | V1+ |
Sie können angeben, welche Ressourcen mit der jeweiligen Ressource verknüpft oder nicht verknüpft werden sollen, indem Sie der Anforderung einen Parameter hinzufügen. Eine Beziehung wird wie folgt angegeben: LINK: <resourceID>; rel = "RelatedResourceType" Die Verwendung dieses Parameters basiert auf dem Entwurf des IETF-Standards. Sie können mehrere Beziehungen hinzufügen, indem Sie diesen Parameter durch ein Komma abgrenzen. Zum Beispiel: LINK: <ID1>; rel="RelatedResourceType1", <ID2>; rel="RelatedResourceType2", <ID3>; rel="RelatedResourceType3" |
|||
X-HTTP-METHOD-OVERRIDE |
|
GET Ressourcen-Sammlung (z.B. /users) oder GET Ressource (z. B. /users/{id})-Anforderungen |
Einige API-Clients haben Probleme beim Senden von Anforderungen mit bestimmten HTTP-Verben wie PUT oder LINK. Um diese Anforderungen zu ermöglichen, kann der Parameter X-HTTP-METHOD-OVERRIDE verwendet werden, um eine bestimmte HTTP-Methode nachzuahmen, während die übrigen Parameter gleich bleiben. Zum Beispiel: X-HTTP-METHOD-OVERRIDE: delete |
Um Daten auf Showpad mit POST oder PUT zu verarbeiten, können 3 verschiedene Inhaltstypen verwendet werden.
Headerfeld-Name | Beschreibung |
---|---|
Content-Type | application/www-url-encoded (PUT + POST) |
multipart/form-data (nur POST) | |
application/json (PUT + POST) |
Hinweise:
- Application/www-url-encoded und multipart/form-data können nur zum Hinzufügen oder Aktualisieren einer einzelnen Ressource verwendet werden.
- Beachten Sie, dass multipart/form-data nur für POST-Anfragen gültig sind.
- Application/JSON kann sowohl zum Aktualisieren einer einzelnen Ressource als auch zum Erstellen einer oder mehrerer Ressourcen verwendet werden.
- Um eine einzelne Ressource zu erstellen, verwenden Sie ein JSON-Schlüsselwert-Array. Wenn Sie mehrere Ressourcen im Batch erstellen möchten, verwenden Sie ein Array der JSON-Schlüsselwert-Arrays.
Abfrageparameter sind Parameter, die an die URL angehängt werden, normalerweise nach dem Pfad der URL. Sie sind als „application/x-www-form-urlencoded“ codiert. Das folgende Beispiel zeigt 3 Parameter: Limit und Offset.
Abhängig von der Art der Anfrage gibt es eine Reihe von Standard-Abfrageparametern:
Parameter | Art | Verfügbarkeit | Beschreibung | |||
---|---|---|---|---|---|---|
Limit | GET ResourceLink-Sammlung | V1 + | Beschränkt die Anzahl der abgerufenen Ressourcen-Links, d.h. ein Limit von 25 gibt 25 Ressourcen-Links zurück. | |||
Offset | GET ResourceLink-Sammlung | V1 + | Versetzt die abgerufenen Ressourcen-Links, d.h. ein Offset von 3 überspringt die ersten 3 Ergebnisse. | |||
Felder | GET Resource oder GET ResourceLink-Sammlung | V1 + | Eine durch Kommata getrennte Liste von Attributen, die in der Antwort wiedergegeben werden sollen. Wird normalerweise verwendet, um die Antwort leichter zu machen. Wenn Sie beispielsweise nur die ID der Ressourcen in einer Sammlung ermitteln möchten, wird durch Angabe von 'id' als Feldparameter nur eine Sammlung von IDs abgerufen. | |||
Methode | GET Resource oder GET ResourceLink-Sammlung | V1 + | Einige API-Clients haben Probleme beim Senden von Anforderungen mit bestimmten HTTP-Verben wie PUT oder LINK. Um diese Anforderungen zu ermöglichen, kann der Parameter 'method' verwendet werden, um eine bestimmte HTTP-Methode nachzuahmen, während der Rest der Parameter gleich bleibt. | |||
describe_model | Alle Anfragen | V1 + | Fügt der Anfrage die Swagger-Modellspezifikation hinzu. | |||
describe_apis | Alle Anfragen | V1 + | Fügt der Anfrage die Showpad-API-Beschreibung hinzu. | |||
suppress_response_codes | Alle Anfragen | V1 + | Einige API-Clients können HTTP-Antwortcodes auf eigene Weise verarbeiten. Einige Clients lösen beispielsweise einen Ausnahmefehler aus, wenn sie einen 40x von 50x empfangen, und lassen keine Möglichkeit, den Inhalt der Antwort zu überprüfen. Wenn Sie 'suppress_response_codes' auf 'true' setzen, werden alle HTTP-Antwortcodes auf 200 gesetzt, damit die Antworten einfacher überprüft werden können. Im 'Meta'-Feld der Antwort wird immer noch der ursprüngliche Antwortcode angegeben, damit weiterhin eine korrekte Auswertung erfolgen kann. |
Die Anzahl der Übereinstimmungen, die Ihrer Anfrage entsprechen, finden Sie im Attribut „count“.
"response": { "count": 29, "items": [...] } |
Die folgenden Headerfelder werden für jede Anfrage gesendet.
Headerfeld-Name |
Beschreibung |
---|---|
access-control-allow-credentials |
Gibt an, welche Standorte an der herkunftsübergreifenden Ressourcenfreigabe teilnehmen können. |
access-control-allow-headers |
Gibt an, welche Standorte an der herkunftsübergreifenden Ressourcenfreigabe teilnehmen können. |
access-control-allow-methods |
Gibt an, welche Standorte an der herkunftsübergreifenden Ressourcenfreigabe teilnehmen können. |
access-control-allow-origin |
Gibt an, welche Standorte an der herkunftsübergreifenden Ressourcenfreigabe teilnehmen können. |
cache-control |
Anweisungen zum Zwischenspeichern für den Server. |
Verbindung |
Steuerungsoptionen für die aktuelle Verbindung |
Inhaltscodierung |
Die Art der für die Daten verwendeten Codierung, normalerweise „gzip“. |
content-type |
Der Medientyp dieses Inhalts, normalerweise „application / JSON“ |
Datum | Datum und Uhrzeit, wann die Nachricht vom Server gesendet wurde. |
Pragma | Caching-Anweisung für den Server, aber für den HTTP/1.0-Client. |
Server | Name des Servers |
transfer-encoding | Form der Codierung, die verwendet wird, um die Einheit sicher auf den Nutzer zu übertragen. |
x-content-type-options | Normalerweise „nosniff“ |
x-frame-options | |
x-newrelic-app-data | |
x-ratelimit-limit | Anzahl der Anfragen, die pro Tag zulässig sind. |
x-ratelimit-remaining | Anzahl der verbleibenden Anfragen. |
x-ratelimit-reset | Datumsstempel des Datums, an dem Ihr Tariflimit zurückgesetzt wird. |
x-robots-tag | |
x-xss-protection |
Code | Name | Beschreibung | Beispiel |
---|---|---|---|
200 | OK | Wird zurückgegeben, wenn eine Anforderung erfolgreich ausgeführt wurde. | GET/users.JSON gibt eine Sammlung von Nutzerlinks zurück |
201 | Created | Wird zurückgegeben, wenn eine Ressource erstellt wird. | POST /users.JSON (wenn die eingegebenen Daten gültig waren) |
400 | Bad Request | Wird zurückgegeben, wenn die Anforderung ungültig ist. Dies ist ein sehr allgemeiner Fehler. | |
401 | Unauthorized | Wird zurückgegeben, wenn ein falsches Zugriffstoken angegeben wurde. | Ein falsches oder abgelaufenes OAuth2-Zugriffstoken wurde gesendet. |
403 | Forbidden | Wird zurückgegeben, wenn der Nutzer nicht über die erforderlichen Berechtigungen verfügt, um auf die Ressource zuzugreifen. | Divisionen sind nur für divisionsfähige Unternehmen zugänglich. |
404 | Not Found | Wird zurückgegeben, wenn eine Ressource nicht gefunden wird. | Die Angabe einer nicht vorhandenen ID wird angegeben. |
405 | Method Not Found | Wird zurückgegeben, wenn eine ungültige HTTP-Methode verwendet wird. | POST /tickets.JSON wird nicht unterstützt. |
409 | Conflict | Wird zurückgegeben, wenn der Nutzer ungültige Daten eingegeben hat. | Erstellen eines Nutzers mit einem nicht eindeutigen Benutzernamen. |
429 | Too Many Requests | Wird zurückgegeben, wenn der Nutzer das Ratenlimit für einen bestimmten Zeitraum überschreitet. | |
500 | Internal Server Error | Wird zurückgegeben, wenn ein Serverfehler auftritt. |