FirstSpirit REST API, 0.0.23
Dokumentation

Anwendungsbeispiele

Sobald die Webanwendung erfolgreich bereitgestellt wurde, ist der REST-Dienst unter dem folgenden Basis-Endpunkt verfügbar:
/rest/v1/

Alle Anfragen müssen einen „Authorization“-Header mit Basic Auth oder einem Bearer-Token enthalten.

Eine vollständige Liste der verfügbaren Endpunkte kann interaktiv über die Swagger-UI eingesehen werden, die unter folgender Adresse erreichbar ist:
/rest/swagger-ui/index.html

Einstiegsbeispiel: Vorlagen erstellen und Inhalte pflegen

„Das folgende Beispiel zeigt anhand mehrerer zusammenhängender Use Cases, wie Vorlagen, Seiten und Inhalte über die REST-API angelegt und bearbeitet werden. Als Beispielprojekt dient eine einfache Seite zum Thema „Kaffee".

Projekt erstellen

Voraussetzung ist ein bestehendes Projekt. Sie können über den folgenden Endpunkt ein neues Projekt erstellen:

/rest/v1/projects/

POST /rest/v1/projects/
Content-Type: application/json

{
  "name": "Coffee Times",
  "description": "The latest news from the world of coffee."
}

Der Rückgabewert enthält die ID des Projekts.

Die Projekt-ID ist im weiteren Verlauf für jede Anfrage notwendig.
{
  "id": 548532,
  "uuid": "bf04cb12-add0-4a59-8d05-5765d3b85d66",
  "name": "Coffee Times",
  "description": "The latest news from the world of coffee."
}

Absatzvorlage erstellen

Die Startseite soll eine Reihe von Artikeln zeigen. Jeder Artikel besteht aus einer Überschrift und einem Inhaltsbereich. Dafür müssen Sie eine Absatzvorlage erstellen:

POST /v1/projects/548532/templates/section-templates/
Content-Type: application/json

{
  "uid": "article",
  "name": "News Article",
  "description": "A single article about coffee"
}

Als Nächstes fügen Sie Formularelemente für die Überschrift und den Inhaltsbereich hinzu. Beachten Sie dabei, dass die GOM-Definition mit dem korrekten Content-Type application/xml übergeben werden muss.

POST /v1/projects/548532/templates/section-templates/article/gom
Content-Type: application/xml

<CMS_MODULE>

  <CMS_INPUT_TEXT name="st_headline" useLanguages="yes">
    <LANGINFOS>
      <LANGINFO lang="*" label="Text" description="Headline of the article"/>
    </LANGINFOS>
  </CMS_INPUT_TEXT>

  <CMS_INPUT_DOM name="st_content" useLanguages="yes">
    <LANGINFOS>
      <LANGINFO lang="*" label="Content" description="Article content"/>
    </LANGINFOS>
  </CMS_INPUT_DOM>

</CMS_MODULE>

Die Ausgabe der Inhalte erfolgt über den standardmäßig angelegten HTML-Ausgabekanal.

GET /v1/projects/548620/template-sets/html

{
  "uid": "html",
  "extension": "html",
  "conversionTable": "Convert HTML",
  "active": true,
  "templateInspectionEnabled": true
}

Da Ausgabekanäle diverse Formate beinhalten können, wird deren Definition als text/plain übergeben.

PUT /v1/projects/548532/templates/section-templates/article/channel-sources/html
Content-Type: text/plain

<div class="article">
    <h1>$CMS_VALUE(st_headline)$</h1>
    $CMS_VALUE(st_content)$
</div>

Seitenvorlage erstellen

Die einzelnen Artikel sollen auf der Startseite untereinander ausgegeben werden. Dazu müssen Sie eine Seitenvorlage erstellen:

POST /v1/projects/548620/templates/page-templates/
Content-Type: application/json

{
  "uid": "homepage",
  "name": "Homepage",
  "description": "List of all articles",
  "bodies": [
    {
      "name": "main",
      "allowedTemplates": ["article"]
    }
  ]
}

Auf der Startseite sollte zu Beginn ein einleitender Text erscheinen. Hierfür müssen Sie weitere Formularfelder für die Seite erstellen:

PUT /v1/projects/548532/templates/page-templates/homepage/gom
Content-Type: application/xml

<CMS_MODULE>
    <CMS_INPUT_TEXT name="pt_title"useLanguages="yes">
        <LANGINFOS>
            <LANGINFO lang="*" label="Title" description="Title of the page"/>
        </LANGINFOS>
    </CMS_INPUT_TEXT>
    <CMS_INPUT_TEXT name="pt_preface"useLanguages="yes">
      <LANGINFOS>
          <LANGINFO lang="*" label="Preface" description="A short introduction"/>
      </LANGINFOS>
  </CMS_INPUT_TEXT>
</CMS_MODULE>
PUT /v1/projects/548532/templates/page-templates/homepage/channel-sources/html
Content-Type: text/plain

<html>
	<head>
		<title>$CMS_VALUE(pt_title)$</title>
	</head>
	<body>
		<h1>$CMS_VALUE(pt_title)$</h1>
		$CMS_VALUE(pt_preface)$
		$CMS_VALUE(#global.page.body("main"))$
	</body>
</html>

Seite anlegen

Mit dem fertigen Template können Sie eine Seite anlegen:

POST /v1/projects/548532/pages/
Content-Type: application/json

{
  "uid": "homepage",
  "templateUid": "homepage"
}
PATCH /v1/projects/548532/pages/homepage/form/pt_title
Content-Type: application/json

{
  "name": "pt_title",
  "type": "CMS_INPUT_TEXT",
  "content": "Coffee Times"
}
PATCH /v1/projects/548532/pages/homepage/form/pt_preface
Content-Type: application/json

{
  "name": "pt_preface",
  "type": "CMS_INPUT_DOM",
  "content": "<i>Coffee Times</i> is your dedicated source for news, trends, and stories from the world of coffee — for enthusiasts and professionals alike."
}

Artikel hinzufügen

Zum Inhaltsbereich main können Sie jetzt beliebig viele Artikel hinzufügen:

PUT /v1/projects/548532/pages/homepage/bodies/main/sections/Columbian%20Harvest
Content-Type: application/json

{
  "templateUid": "article"
}
PATCH /v1/projects/548532/pages/homepage/bodies/main/sections/Columbian%20Harvest/form/st_headline
Content-Type: application/json

{
  "name": "st_headline",
  "type": "CMS_INPUT_TEXT",
  "content": "Colombian Harvest Reaches Record High"
}
PATCH /v1/projects/548532/pages/homepage/bodies/main/sections/Columbian%20Harvest/form/st_content
Content-Type: application/json

{
  "name": "st_content",
  "type": "CMS_INPUT_DOM",
  "content": "Coffee farmers in Colombia have reported an exceptional harvest this season, with production figures surpassing all previous records."
}

Seite freigeben

Sobald die Bearbeitung der Inhalte abgeschlossen ist, können Sie die Seite freigeben:

POST /v1/projects/548532/pages/homepage/actions
Content-Type: application/json

{
  "action": "release",
  "options": {
    "checkOnly": false,
    "dependentReleaseType": "NO_DEPENDENT_RELEASE",
    "ensureAccessibility": false,
    "recursive": false
  }
}

Seitenreferenz erstellen

Damit die Seite an der richtigen Stelle generiert wird, müssen Sie eine entsprechende Referenz erstellen.

Für die Erstellung der Referenz benötigen Sie die Seiten-ID.

GET /v1/projects/548532/pages/homepage

{
  "id": 548581,
  "gid": "6e226dc4-f91d-4ddb-93bb-285c6b3f4f09",
  "projectId": 548532,
  "uid": "homepage",
  [...]
}


POST /v1/projects/548532/page-references/
Content-Type: application/json

{
  "uid": "homepage",
  "pageId": 548581,
  "location": "/"
}

Zum Abschluss müssen Sie außerdem die Seitenreferenz freigeben:

POST /v1/projects/548532/page-references/homepage/actions
Content-Type: application/json

{
  "action": "release",
  "options": {
    "checkOnly": false,
    "dependentReleaseType": "NO_DEPENDENT_RELEASE",
    "ensureAccessibility": false,
    "recursive": false
  }
}

Seiteninhalte