Headless Server Manual
Total Page:16
File Type:pdf, Size:1020Kb
COREMEDIA CONTENT CLOUD Headless Server Manual Headless Server Developer Manual Headless Server Manual | Copyright CoreMedia GmbH © 2021 CoreMedia GmbH Ludwig-Erhard-Straße 18 20459 Hamburg International All rights reserved. No part of this manual or the corresponding program may be reproduced or copied in any form (print, photocopy or other process) without the written permission of CoreMedia GmbH. Germany Alle Rechte vorbehalten. CoreMedia und weitere im Text erwähnte CoreMedia Produkte sowie die entsprechenden Logos sind Marken oder eingetragene Marken der CoreMedia GmbH in Deutschland. Alle anderen Namen von Produkten sind Marken der jeweiligen Firmen. Das Handbuch bzw. Teile hiervon sowie die dazugehörigen Programme dürfen in keiner Weise (Druck, Fotokopie oder sonstige Verfahren) ohne schriftliche Genehmigung der CoreMedia GmbH reproduziert oder vervielfältigt werden. Unberührt hiervon bleiben die gesetzlich erlaubten Nutzungsarten nach dem UrhG. Licenses and Trademarks All trademarks acknowledged. September 08, 2021 (Release 2107 ) COREMEDIA CONTENT CLOUD ii Headless Server Manual | 1. Preface ................................................................................ 1 1.1. Audience .................................................................... 2 1.2. CoreMedia Services ........................................................ 3 1.2.1. Registration ....................................................... 3 1.2.2. CoreMedia Releases ............................................. 4 1.2.3. Documentation .................................................. 4 1.2.4. CoreMedia Training .............................................. 8 1.2.5. CoreMedia Support .............................................. 8 1.3. Typographic Conventions ................................................ 10 1.4. Changelog ................................................................. 12 2. Overview ............................................................................. 13 3. Configuration and Operation ....................................................... 15 3.1. Configuration of the Headless Server ................................... 16 3.2. Endpoints of the Headless Server ....................................... 17 3.3. Preview .................................................................... 19 3.3.1. JSON Preview Client ............................................. 19 3.3.2. Custom Preview Client ......................................... 20 3.4. Security ................................................................... 21 3.4.1. Whitelisting of GraphQL Queries ............................... 22 3.4.2. Limiting the Size of a Search Result .......................... 22 3.4.3. Limiting the Depth of a GraphQL Query ....................... 22 3.4.4. Limiting the Complexity of a GraphQL Query ................. 23 3.4.5. Enforcing an Execution Timeout for GraphQL Queries ....... 23 4. Development ....................................................................... 25 4.1. Defining the GraphQL Schema ........................................... 26 4.2. Headless Server Implementation with GraphQL-Java ................. 28 4.2.1. Bootstrapping an Executable Schema ........................ 28 4.2.2. TypeDefinitionRegistry ......................................... 28 4.2.3. RuntimeWiring ................................................. 28 4.2.4. Invoking Queries ............................................... 30 4.3. The @fetch Directive ..................................................... 32 4.4. The @inherit Directive ................................................... 34 4.5. Model Mapper ............................................................ 35 4.6. Filter Predicates ......................................................... 36 4.7. Adapter ................................................................... 37 4.8. Building Links ............................................................ 39 4.8.1. Link Composer for ID links ..................................... 39 4.8.2. Link Composer for hyperlinks ................................. 39 4.8.3. Implementing Custom Link Composer ....................... 40 4.9. Content Schema ......................................................... 41 4.9.1. Simple Article Query ............................................ 41 4.9.2. Article Query with Fragments and Parameters ............... 42 4.9.3. Querying all available Sites .................................... 43 4.9.4. Site Query ....................................................... 43 4.9.5. Querying derived Sites ......................................... 45 4.9.6. Page Query ..................................................... 45 4.9.7. Download Query ................................................ 49 4.9.8. External Link Query ............................................ 49 4.9.9. Querying localized variants ................................... 50 COREMEDIA CONTENT CLOUD iii Headless Server Manual | 4.10. Using Time Dependent Visibility ........................................ 51 4.11. Remote Links ............................................................ 52 5. Rich Text ............................................................................ 55 5.1. Rich Text Output .......................................................... 56 5.1.1. The Include Directive ........................................... 58 5.1.2. YAML Anchors and Aliases ..................................... 58 5.1.3. Code Comments ............................................... 59 5.1.4. Name Property ................................................. 59 5.1.5. Elements Property ............................................. 59 5.1.6. Classes Property ............................................... 60 5.1.7. Contexts and InitialContext Property .......................... 60 5.1.8. HandlerSets Property .......................................... 68 5.1.9. Internal Links ................................................... 68 5.1.10. External Links ................................................. 69 5.2. Using RichTextAdapters for Different Rich Text Grammars ............ 71 5.2.1. Rich Text Adapters .............................................. 71 5.2.2. Developing Custom RichTextAdapters ........................ 72 5.2.3. CoreMedia Grammar RichTextAdapter ........................ 74 6. Search Extension .................................................................. 75 6.1. Generic Search ........................................................... 76 6.2. Dynamic Query Lists ..................................................... 79 6.3. Custom Filter Queries .................................................... 81 7. eCommerce Extension ............................................................. 83 7.1. Headless Commerce Integration Architecture ......................... 84 7.2. Augmentation ............................................................ 86 7.2.1. Categories and Products Mapped to Media Content ......... 86 7.2.2. Augmented Categories and Products ......................... 87 7.2.3. Augmented Pages ............................................. 89 7.3. Product Lists .............................................................. 91 7.4. References to Products and Categories ................................ 92 7.5. eCommerce Setup and Configuration .................................. 94 8. Personalization Extension ......................................................... 95 8.1. Retrieve CMSelectionRules Documents ................................. 96 8.2. Rules ...................................................................... 97 9. Persisted Queries ................................................................. 100 9.1. Loading Persisted Queries at Server Startup ........................... 101 9.1.1. Defining Persisted Queries in Plain GraphQL .................. 101 9.1.2. Defining Persisted Query Maps in Apollo Format ............ 102 9.1.3. Defining Persisted Query Maps in Relay Format ............. 103 9.2. Plugin support for persisted queries ................................... 104 9.3. Query Whitelisting ....................................................... 105 9.4. Apollo Automatic Persisted Queries ................................... 106 10. REST Access to GraphQL ......................................................... 107 10.1. Mapping REST Access to Persisted Queries ........................... 109 10.2. JSLT Transformation ................................................... 110 11. Site Filter ........................................................................... 111 12. Media Endpoint ................................................................... 112 12.1. Media Endpoint URLs ................................................... 114 12.2. Configuration of Media Endpoints ..................................... 116 COREMEDIA CONTENT CLOUD iv Headless Server Manual | 13. Metadata Root .................................................................... 117 13.1. PDE Mapping as Metadata .............................................. 118 14. Frontend Client Development ................................................... 120 14.1. Getting Started .......................................................... 121 14.1.1. Prerequisites ................................................... 121 14.1.2. Setting up a React App ....................................... 121 14.1.3. Setup Apollo for GraphQL ..................................... 122 14.1.4. Developer Tools ............................................... 122 14.2.