Publisher-Verwaltung über die V6 REST-API

Einleitung

Publisher-Verwaltung

~~Die~~über die V6 REST-API ~~ermöglicht~~

Authentifizierung

Erforderliche ~~Admins,~~Header ~~Publisher~~für ~~anzulegen~~alle ~~und deren Details auszulesen. Die Funktionalität beschränkt sich aktuell auf~~ ~~CREATE~~ ~~und~~ ~~READ~~~~-Operationen.~~Anfragen:

Header Beschreibung X-Network-ID Netzwerk-ID, z.B. -1 für global X-Auth-Token API-User-Token X-Auth-ID API-User-Login-ID Content-Type application/json

EndpointEndpunkt

~~Für~~Base ~~Admins:~~URL: https://SUBDOMAIN.de/ws/V6/admin/REST/Publisher~~Hinweis:~~

~~Die Publisher-API verwendet den REST-Endpunkt. Bei GET-Anfragen mit Filtern~~

Es werden die ~~Filterparameter~~üblichen ~~über~~HTTP-Methoden ~~die~~verwendet: ~~params~~POST ~~[...]~~zum ~~übergeben.~~Anlegen, GET zum Abrufen.

CRUD-Operationen

CREATE

POST: Publisher erstellenOperation (CREATE)

~~Erstellt einen neuen Publisher und fügt die entsprechenden Daten in die Tabellen~~ global.logins ~~und~~ global.login_settings ~~ein.~~

POST)

Methode & Pfad: POST /ws/V6/admin/REST/Publisher

Erforderliche Parameter:Parameter

Parameter	Typ	Beschreibung
`email`	String	~~Pflichtfeld, max.~~Max. 255 Zeichen
`salutation`	String	~~Pflichtfeld, Werte:~~z.B. `mr` ~~oder~~ /`mrs`
`prename`	String	~~Pflichtfeld, max.~~Max. 255 Zeichen
`surname`	String	~~Pflichtfeld, max.~~Max. 255 Zeichen

Optionale Parameter

~~(Auszug):~~

company, street, zip, city, telephone, country (ISO 3166 ALPHA-3), billing_sepa_owner, billing_sepa_iban, billing_sepa_bic, companytype (z.B. un ~~oder~~ /priv), language_interface (Default: DEU), billing_mode (Default: 1), billing_media (Default: 1), country_billing (Default: DEU), country_publisher (Default: DEU), billing_limit (Default: 25), dialog_email (Default: Wert von email)

Für salutation, companytype und country gibt es keine feste Werteliste, die serverseitig erzwungen wird — bitte trotzdem an die üblichen Werte halten, damit nachgelagerte Auswertungen (Rechnungsstellung, Sprachwahl etc.) korrekt funktionieren.

Response

{
  "data": {
    "id": 123,
    "name": "Max Mustermann",
    "email": "max.mustermann@example.com"
  },
  "log": "no logmessage provided",
  "sessionId": "",
  "session": null
}

Die eigentlichen Daten stehen im data-Feld.

READ Operation (GET)

~~Beispiel-Request:~~Methode & Pfad: GET /ws/V6/admin/REST/Publisher bzw. GET /ws/V6/admin/REST/Publisher/{id}

Einzelnen Publisher abrufen

GET /ws/V6/admin/REST/Publisher/{id} — id ist Teil des URL-Pfads, keine Query-Parameter.

Liste abrufen (mit Filtern)

Filter werden als Query-Parameter im Format params[feld]=wert übergeben, z.B.:

curlGET -X/ws/V6/admin/REST/Publisher?params[status]=1
POST

-H

Filterbar sind sowohl die Basis-Felder des Publisher-Accounts (id, status, type) als auch alle Felder aus dem Registrierungsprozess (email, prename, surname, company, street, zip, city, telephone, country, Billing-Felder etc.). Mehrere Filter zusammen werden UND-verknüpft, z.B.:

GET /ws/V6/admin/REST/Publisher?params[status]=5&params[prename]=Max

Filter auf Registrierungsfelder sind exakte Treffer (kein Teilstring-/Wildcard-Match).

Status-Werte

Bekannte Werte für status:

Status Bedeutung 1 Bestätigter, aktiver Publisher 5 Neu registriert, noch nicht freigegeben

(Für eine vollständige Übersicht aller möglichen Status-Werte bitte im Admin-Interface unter der Publisher-Verwaltung nachsehen.)

Response-Format der Liste

{
  "Content-Type:data": application/json" -H{
    "X-Network-ID:123": -1" -H{
      "X-Auth-Token: ADMIN_APIUSER_TOKEN" -Htype": "X-Auth-ID:pub",
      ADMIN_APIUSER_LOGIN_ID""id": -d123,
      '"status": 5,
      "settings": {
        "email": "max.mustermann@example.com",
  "salutation": "mr",
        "prename": "Max",
        "surname": "Mustermann",
        "company": "Musterfirma"",
        "street": "MusterstraßeMusterstraße 1",
        "zip": "12345",
        "city": "Musterstadt",
        "country": "DEU",
        "billing_sepa_owner"...": "Maxweitere Mustermann"im Registrierungsprozess gespeicherte Felder"
      }
    }
  },
  "billing_sepa_iban"log": "DE12345678901234567890"no logmessage provided",
  "billing_sepa_bic"sessionId": "GENODEF1M01"",
  "language_interface"session": "DEU",
  "billing_mode": 1,
  "billing_media": 1,
  "country_billing": "DEU",
  "country_publisher": "DEU",
  "billing_limit": 50
}' "https://SUBDOMAIN.de/ws/V6/admin/JSON/Publisher"

~~Erwartete Antwort:~~

{
  "id": 123,
  "name": "Max Mustermann",
  "email": "max.mustermann@example.com"null
}

Das

GET:`settings`-Objekt enthält alle für den Publisher auslesengespeicherten Registrierungsdaten — welche Felder konkret enthalten sind, hängt davon ab, was beim jeweiligen Publisher tatsächlich hinterlegt wurde (READ)

kein festes Schema).

~~Gibt~~Bekannte Einschränkung: Informationen zur Werbefläche (Werbefläche/Werbeflächen-URL), die ~~Details~~im ~~eines~~Registrierungsprozess ~~spezifischen~~ebenfalls ~~Publishers~~abgefragt ~~oder~~werden, ~~eine~~sind ~~Liste~~über ~~von~~diese ~~Publishern~~API ~~zurück.~~
aktuell
~~Filteroptionen:~~nicht ~~Alle~~abrufbar. ~~Felder~~Das ~~der Tabelle können~~wird als ~~Filter~~Erweiterung ~~verwendet~~nachgezogen.
~~werden~~

~~(z.~~

Beispiele

Einzelner Publisher: email, status, prename, surname).

~~Beispiel-Request (spezifische ID):~~

curl -X GET -H "Content-Type: application/json" -H "X-Network-ID: -1" -H "X-Auth-Token: ADMIN_APIUSER_TOKEN" -H "X-Auth-ID: ADMIN_APIUSER_LOGIN_ID" "https://SUBDOMAIN.de/ws/V6/admin/JSON/Publisher?id=123"REST/Publisher/123

Neu

~~Beispiel~~registrierte, ~~für~~noch nicht freigegebene Publisher: GET mit Filtern:

curl -X GET -H "Content-Type: application/json" -H "X-Network-ID: -1" -H "X-Auth-Token: ADMIN_APIUSER_TOKEN" -H "X-Auth-ID: ADMIN_APIUSER_LOGIN_ID" "https://SUBDOMAIN.de/ws/V6/admin/JSON/REST/Publisher?status=1&prename=Max"params[status]=5

Publisher per E-Mail suchen: GET /ws/V6/admin/REST/Publisher?params[email]=max.mustermann@example.com

Fehlerbehandlung

Fehler

~~Fehlende~~werden ~~Pflichtfelder~~in ~~(POST):~~folgendem Format zurückgegeben:

{
  "error": true,
  "msg": "<Fehlerbeschreibung>",
  "type": "Ws\\Error",
  "data": []
}

Der HTTP-Statuscode ist bei Fehlern durchgängig 500.

Fehler Beispiel-msg Fehlendes Pflichtfeld bei CREATE internal server error. Details: Missing required field: email"email } Publisher nicht gefunden ~~(GET):~~internal

{server "error":error. "PublisherDetails: Model not found"found.

} Filter ohne Treffer kein Fehler — liefert "data": []