core-bundle
core-bundle copied to clipboard
contao
API use cases
As briefly discussed on this year's conference, we want to add an API to Contao so we can build apps for it. We have already agreed that it is difficult to build a general API without concrete use cases, therefore we are now collecting API use cases and kindly ask you to help us.
So if you have a use case for an API, please describe it below (in English or German).
Thank you in advance. 😄
Also ich persönlich nutzt meine eigene JSON-Api um z.B. die Ausgabe einzelner Module in diveresen Apps (Android/iOS) zu steuern. Vereinheitlichen kann man das Core News und Eventmodul, sowie die meisten Inhaltselemente.
Konkreter Anwendungsfall: Nachrichten-Apps für Tageszeitungen.
Eine API wäre sehr cool! Dazu folgende Use Cases:
- Ein Kunde von uns hätte gerne eine App, die Daten aus Contao ausliest, damit Inhalte nicht doppelt gepflegt werden müssen. Das heißt, die integrierten Funktionen (Content, News, FAQ etc.) müssten über die API bereitgestellt werden. Dazu kommt noch, dass eigene Extensions ebenfalls über die API abrufbar sein müssten. Das wäre aber wieder die Aufgabe der jeweiligen Entwickler. Vielleicht könnt ihr dafür eine Basisklasse (so etwas wie ContaoApiController) bereitstellen :-)
- Bei einem Onlineshop mit Isotope wäre es cool, wenn man alle Produkte als JSON bekommt. So kann man immer den aktuellen Stand auslesen und z.B. den Partnern zur Verfügung stellen.
Ja eine JSON-API zum Abruf fände ich auch toll. Evtl. hierbei noch die Möglichkeit einer Whitelist einräumen, damit nur bestimmte Domains die Inhalte abgreifen können/dürfen.
I do not have a real use-case, but I think it would be good to use a GraphQL-API. Because of the high modularity of Contao, you can add custom tables and fields to the database very easily. But with a REST-API you would have to write your own endpoints or extend existing ones to have access to the data.
With a GraphQL-API it would be easier to handle those cases, because the client itself requests the fields.
@simonreitinger
Das heißt, die integrierten Funktionen (Content, News, FAQ etc.) müssten über die API bereitgestellt werden.
Darüber haben wir auf der Konferenz auch gesprochen. Bei diesem Fall (und vielen anderen) stellt sich aber zwangsläufig die Frage, was genau man denn erwarten würde: Rohdaten einer News? Final gerendertes HTML einer News inkl. Kindelementen, also quasi der Output des News-Leser-Moduls? Eine Mischung aus beiden?
Vielleicht könnt ihr dafür eine Basisklasse (so etwas wie ContaoApiController) bereitstellen :-)
Das ist ein wichtiger Punkt: Es wäre aber schön, wenn im Core zumindest ein Standard etabliert werden würde, an denen sich alle Extension-Entwickler halten, damit nicht jeder sein eigenes Süppchen kocht ;)
Praktisch wäre eine API die sich am DCA orientiert und alle Rohdaten ausgibt/bearbeiten/löschen kann etc. Dann kann man Daten ausgeben in anderen Tools/Seiten etc. oder auch Nutzer aus einer externen Software anlegen/verwalten etc.
Basierend auf Anforderungen einzelner realisierter Projekte, sehe ich folgende Use-Cases:
Inhalts-API
- Abruf der Inhalte verschiedener Typen z.b. News, Events, Artikel usw.
- Ausgabeformat bestimmbar, gerendertes HTML oder aufgebereitete strukturierte Daten (JSON, XML)
Formular-API
- Abruf des Formulars (HTML, strukturiertes Formnat mit Meta-Informationen welche Felder existieren -> Rendering im Frontend ermöglichen)
- Absenden von Formularen des Formulargenerators
- Datenformat der Antwort definierbar (HTML, JSON, XML)
Backend-API
- Abbildung der DC_-Treiber mittels API ähnlich wie @Wusch es beschrieben hat
Mir ist bewusst, dass sich viele der Wünsche bedeuten würden, die Art und Weise wie Contao arbeitet neu zu definieren ;-)
Ich kann das Symfony API Platform Bundle empfehlen.
https://api-platform.com
Damit kann via Annotation eine Entity erweitert werden und dadurch wird eine Standard Rest API (Post, Get, Put, Delete) mit Pagination, Filter, Swagger Doku und einigen API Standards generiert. Individuelle API Endpunkte können auch erstellt werden.
Das einzige was halt benötigt wird sind Entities, aber das müsste ja inzwischen in Contao 4 implementiert sein?!
Vom Usecase her würde das eine Standard API abbilden, die es ermöglicht auf alle Daten in Contao zuzugreifen.
Ich habe gerade ein Projekt, bei dem wir ausschließlich auf so eine API gesetzt haben und bis auf Dateiuploads konnten wir damit alles umsetzen.
Endpunkte für eine Standard Entity (bsp. Article): GET /api/articles POST /api/articles GET /api/articles/1 PUT /api/articles/1 DELETE /api/articles/1
Mit dem API Platform Bundle haben wir auch schon experimentiert; aber das macht meines Erachtens nur Sinn, wenn man ein System hat, was vollständig auf Entities aufbaut. Und entgegen deiner Hoffnung ist das in Contao 4 nicht der Fall und ist vermutlich auch in weiter Ferne ;-) Wenn das nicht der Fall ist, ist das Platform-Bundle meines Erachtens viel zu umfangreich und mächtig. Wir haben damit experimentiert, einen CustomDataProvider für die Anbindung des Contao Model-Layers an das PlatformBundle zu schreiben, aber meines Erachtens ist das wenig zielführend.
Let's maybe stick to use cases first. Contao needs to be adopted to suit the needs anyways (thinking of permissions, data representation, etc)
- JavaScript based Single Page Applications
- Alexa Skills or Google Assistent
- Click ans Play chatbots like Chat fuel
- As fulfillment for Dialogflow
- App Shell Model based PWA‘s
So far we've been using Contao-APIs for
- JS-driven Web-Apps
- PWAs
- Mobile Apps
- Exports into other systems (fetch Contao data and generate PDFs)
Just my 2 cents: I think GraphQL is the way forward. Just a coincidence, but we actually started writing one three days ago ;)
GraphQL is also used with GatsbyJS (https://www.gatsbyjs.org/) this would be an other use case for the Contao API (for me). Gatsby is a great tool for PWA's!
Wir hatten auch schon einige Projekte bei denen wir uns selbst APIs zurechtzimmern mussten:
- Auslieferung von fertig gerenderten Inhaltselementen via JSON API
- Abruf und Modifikation von Newsbeiträgen zur weiteren Bearbeitung in externen Systemen
- Ganz proprietäre API für eine Erweiterung eines Kunden die garnichts mit dem Core zu tun hat aber eben extra als Bundle gebaut werden musste damit wir
/api/als Endpoint nutzen können
So here's briefly what we've discussed at the core developer's meeting.
Facts:
- Building a general API that fits everybody's needs out of the box is a utopian dream. So we need something that builds the foundation for developers to extend the functionality and some possiblity for editors to configure some basic API endpoints.
- GraphQL and REST APIs both have their respective use cases. If you believe one is better than the other, you did not read into the topic properly.
- REST is especially well suited for retrieving assets because of HTTP caching. That's where it really shines. For write operations, you should not blindly dive into REST but also consider good old RPC. Use the best tool for a given use case, not the one that everybody thinks is the fanciest one.
- Write operations are way more complicated to implement than read operations due to permissions and validation.
- 95% of all use cases as of today are READ operations.
So we agreed that this huge topic needs to be tackled bit by bit and we would like to start with basic read endpoints (GET).
This is roughly an idea we came up with:
Any developer should be able to define a type of resource. E.g. a news list. It's the developer's responsiblitly to define a JSON schema and load the data in this endpoint accordingly. The resources are not exposed to the world by default but instead it must be explicitly configured by the user adding an entry in e.g. tl_api. Ideally this would also be possible by configuration so both, app configuration and DB entries by the admin are merged. Any developer can provide any kind of additional configuration such as e.g. for the newslist a restriction to a given news archive etc. Also, permissions should be considered here (allow endpoint access only by user(group) X).
By default, the whole data is returned as defined in the JSON schema by the developer. The user should be able to restrict that data though. Let's say you have the following data for news entries:
{
"id": 42,
"title": "Foobar",
"author": {
"id": 15,
"firstname": "John",
"email": "[email protected]"
}
}
Maybe you don't want to expose the email and id of a user to the world but only the firstname so you could specify all the data you want using JSONPath:
$.id
$.title
$.author.email
We're not sure if that can work out but after about 2.5 hours this is the solutions we came up with that seems the most flexible yet still comprehensible (for an admin) configuration. Defining a JSON schema would force developers to learn JSON schema but also comes with huge advantages. Most notably we could maybe autogenerate an OpenAPI documentation endpoint. Something which we really think is very important.
These are just ideas and I wrote them down here so we don't forget about it. Nothing here is to be expected to be implemented anytime soon but I'll give it a try at some time or another. 😄
To put it in short - Headless mode with GraphQL output and ability to use GatsbyJS. Contao could serve as a central point for information delivery for web, apps, amp, etc.
@wschwaiger i prefer general JAM Stack Support (https://jamstack.org/). There are a lot of static site generators out there. This is a great chance to grow up. At the moment it seems like netlify is the only open source cms to manage content for static site generators https://www.netlifycms.org/
One more comment. I think this is how it should be, https://www.youtube.com/watch?v=GX9z5M9mz30
Hier mal eine kurze Zusammenfassung der API-Session beim Contao Camp in Leipzig:
Trennung von Backend- und Frontend-API
Es ist sinnvoll, getrennte APIs für Backend- und Frontend-Funktionen zu erstellen. Die Backend-API ist dabei primär zur Verwaltung der Daten als Zugriff zum DCA gedacht, während die Frontend-API schon fertig gerenderte Inhalte liefern kann und eher in Richtung Headless CMS geht.
Bei der Session waren wir uns relativ einige, dass eine Backend-API Priorität hat und eher heute als morgen implementiert werden sollte.
Ob RESTful oder GraphQL wurde noch offen gelassen aber für REST spricht wohl die einfachere Implementierung und das besser Caching. Als Autorisierung bietet sich OAuth an. Dem jeweiligen Access-Token kann dann ein Backend-Nutzer zugeordnet werden, dessen Berechtigung genutzt wird. Sinnvoll wäre sicherlich auch ein reiner Lesezugriff und eine zeitliche Beschränkung für einen Token. Hier mal beispielhaft, wie das bei der WooCommerce REST-API implementiert ist.
Existierende API-Erweiterungen
Bei der Session hatten wir kurz diese bestehenden Erweiterungen erwähnt:
- heimrichhannot/contao-api-bundle
- leadingsystems/contao-api
- DieSchittigs/contao-content-api-bundle (Danke @bezin für den Hinweis)
@leofeyer wollte sich diese mal etwas näher anschauen. Vielleicht kann man da ja was als Ausgangspunkt nutzen. Einig waren wir uns aber, dass die API in den Core gehört (zumindest hatte ich es so aufgefasst).
Bei meiner Suche hatte ich noch ein Symfony-Bundle gefunden, welches vielleicht interessant ist:
Versionen
Sinnvoll ist es sicherlich, anfangs nicht alles zu implementieren und die API nach und nach weiterzuentwickeln. Entsprechend könnte es dann verschiedene Versionen der API geben, welche über entsprechende Endpoints (/v1, /v2, …) oder Versions-Header angesprochen werden. Zur Gewährleistung der Rückwärtskompatibilität sollte dann immer mindestens die vorherige API-Version weiter unterstützt werden.
Korrigiert oder ergänzt mich, wenn ich bei der Session was vergessen oder falsch verstanden habe.
Danke für deine Zusammenfassung der Session: Wir hatte uns auch noch dieschittigs/contao-content-api-bundle angesehen :)
weitere Projekte:
- JSON-API https://contao.org/de/erweiterungsliste/view/jsonapi.de.html
- RESTfull-Webservice https://github.com/Craffft/contao-restful-webservices
Dank an die gute Zusammenfassung - Link kommt mit in die Sessionübersicht CC18 https://contao.org/de/veranstaltungen/contao-camp-2018.html
Erstmal vielen Dank schonmal für die Überlegungen und Ansätze, eine Content API zu entwickeln! Ist das Thema noch für kommende Versionen aktuell?
Soweit bekannt, finden keine aktiven Arbeiten an einer API statt. Es gibt einige Drittanbieter-Bundles aber im Core-Team auf jeden Fall im Moment nicht.