RESTful API: Vorstellung

hbuerger

@philipptrenz sagte in RESTful API: Vorstellung:

Hey, vielen Dank für das Bereitstellen der API.

Ich wurde von meiner Gemeinde angefragt, ob ich ein kleines Desktop-Tool schreiben kann, dass die Gottesdienstbesucher in ChurchTools einträgt ohne sich im Webportal einloggen zu müssen. Ist schon absehbar wann diese Funktionalität implementiert sein wird?

Vielen Dank!

Du meinst sicherlich die Fakten im Events Modul, oder? Nein darüber haben wir aktuell noch nicht gesprochen.

philipptrenz

@hbuerger Genau! Okay, aber ist der Events-Endpoint schon in Planung? Nachdem die Facts ja frei konfigurierbar sind würde ich für den Endpunkt einfach ein Array mit Key-Values zum Lesen und Setzen vorschlagen.

In etwa so

GET /events/{id}/facts

Returns: 
{
  "data": [
    {
      "key": "Besucherzahl",
      "value": 57
    },
    {
      "key": "Kollekte",
      "value": 0
    }
  ]
}

und

PUT /events/{id}/facts

Request body: 
{
  "data": [
    {
      "key": "Besucherzahl",
      "value": 57
    },
    {
      "key": "Kollekte",
      "value": 165
    }
  ]
}

Das sollte generisch genug sein, um auch spätere Erweiterungen an den Facts abbilden zu können.

Ich fände es klasse, wenn das Feature zeitnah Einzug erhält. Ich habe nämlich wenig Lust mich mit der alten API herumzuschlagen

Btw: Wird es eine veröffentlichte Swagger-Spezifikation für die API geben, um sich mit Swagger CodeGen den Client-Code generieren lassen zu können?

davidschilling

@philipptrenz sagte in RESTful API: Vorstellung:

Btw: Wird es eine veröffentlichte Swagger-Spezifikation für die API geben, um sich mit Swagger CodeGen den Client-Code generieren lassen zu können?

Diese Spezifikation gibt es schon. Eine Nutzung davon siehst du wenn du /api bei euch in der Installation aufrufst.
Die spezifikation findest du unter https://$DEINE_GEMEINDE.church.tools/system/runtime/swagger/openapi.json
$DEINE_GEMEInDE musst du natürlich austauschen.

philipptrenz

@davidschilling Perfekt, den Link zur JSON-Spezifikation hab ich gesucht. Danke dir!

MarkusFriesen

Hi @hbuerger. Vielen Dank für die API, bin gerade drauf gestoßen und finde sie super Hilfreicht!

Ich habe eine kurze frage zur Erweiterung. Ich habe es geschafft meine Gemeinde dazu zu überreden das wir unsere Lieder Datenbank in die Cloud zu ChurchTools ziehen.

Die Song api kann ja aber zur Zeit nur lesen. Habt ihr euch auch überlegt API's zum erstellen von Songs, und für das automatisierte hochlanden von z.b. songbeamer sng dateien zu ermöglichen?

Das wäre super Hilfreich.

Danke.

bwl21

@markusfriesen Du kannst jenseits der dokumentierten RESTful API auch die alte API nutzen. Die musst du halt ein bisschen ausforschen, im Browser die Entwicklertools aufmachen, einen Song hochladen und im Netzwerktab schauen, was da läuft.

jziegeler

@bwl21 wobei du die alte API nur für das erstellen der Songs bräuchtest. Für die Dateien gibt es eine eigene file-API bei der du den domaintype song angeben kannst

bwl21

@jziegeler danke für den Hinweis, das ist natürlich richtig.

MarkusFriesen

@bwl21 Stimmt, das funktioniert natürlich auch. Probiere ich aus. Danke.

MaBo

Wiki APIs

Moin, ich baue gerade div. Automatisierungen für uns.

Leider fehlt mir die Put / Post API für's Wiki um Seiten zu erstellen oder zu aktualisieren (/wiki/categories/{wikiCategoryId}/pages/{identifier}).

Frage: wann sollen die kommen? Ich gehe davon aus, dass Ihr da schon was auf der Agenda habt.

@jziegeler

narnitz

@MaBo Aktuell ist da glaube ich noch nichts fest geplant, aber du kannst (wenn du den ChurchTools Client nutzt) die alte Funktion churchwiki/ajax der alten API Nutzen.

Die Payload sieht dann so aus:

{
    "doc_id": "main",
    "wikicategory_id": 11,
    "val": "# Test",
    "auf_startseite_yn": false,
    "identifier": "2e39dfbb-7127-4d9d-a3d2-0b96d94cd96f",
    "browsertabId": 12345678,
    "is_markdown": true,
    "func": "save"
}

MaBo

@narnitz sagte in RESTful API: Vorstellung:

churchwiki/ajax

Danke für die flotte Hilfe. Leider bin ich mit der alten API verloren... Ich werde mit https://api.church.tools/ einfach nicht warm.

Gibt es jmd, der mich etwas abholen kann oder eine umfassende Doku?

narnitz

@MaBo Nutzt du den ChurchTools JS Client?

MaBo

@narnitz
Nope, python. Doch der JS Client unterstützt (wie ich verstanden habe) die alte API nicht. Sonst würde mir das als Basis reichen.

Und mit php (https://github.com/5pm-HDH/churchtools-api) bin ich nicht fit genug...

narnitz

@narnitz Generell kannst du dir auch die Request einfach mal anschauen, die abgeschickt wird, wenn du eine Wikiseite speicherst:
Beispielsweise beim Bearbeiten einer Wikiseite ist das:
Ein POST an https://instanzName.church.tools/?q=churchwiki/ajax
Mit dem Cookie und Csrf-Token als Header (hier sollte aber auch ein login token gehen, siehe https://hilfe.church.tools/wiki/0/API Authentifizierung und https://hilfe.church.tools/wiki/0/API-CSRF

Und der Request Body ist dann das JSON, das auch oben schon steht.

narnitz

@MaBo Doch, das tut er.

Das müsste mit churchToolsClient.oldApi('churchwiki/ajax') gehen.

@jziegeler könntest du hier vllt. noch einen Tipp geben?

MaBo

Moin @narnitz , ich bin schon ein ganzes Stück weiter. Leider habe ich lange nicht mitbekommen, dass meine requests wegen der 2-FA nicht erfolgreich waren.

Kaum habe ich einen Testuser genutzt, kam ich durch. Nun hänge ich "nur" noch daran, dass er keine Berechtigungen haben soll (BasicAuth+Cookies, CSRF und Token hab ich schon versucht, mal sehen was da fehlt).

Auf jeden Fall: DANKE für die Unterstützung, die hat mich weiter gebracht!

narnitz

@MaBo du kannst mit der neuen API mit /api/login und /api/totp dich authentifizieren können. Danach kannst du dir auch deinen Login Token über den endpoint (der mir gerade nur leider nicht einfällt) rauslassen.

Die Dokumentation zur REST api findest du wie gewohnt unter https://deineinstanz.church.tools/api

MaBo

@narnitz merci

noch hab ich das mit TOTP nicht zum laufen bekommen, doch der rest funktioniert super.

(wer genauers wissen will kann hier schauen: GitHub - ChurchTools-song-checker)

Nun aber genug mit OT