[Contentful Essentials] Delivery architecture and APIs

Transcript

1. 1 Delivery architecture and APIs Charlie Chrisman, Solutions Engineer February 20, 2019
2. Housekeeping • This webinar is being recorded; we will share the recording and slide deck with all registrants • Please leave your questions in the Q&A box, we’ll answer them after the presentation • To get in touch, write to us at team@contentfulmail.com before we begin...
3. 3 1. The “API first” approach 2. Content delivery architectures 3. Contentful Core APIs 4. SDKs 5. GraphQL Content API Topics
4. 4 1. Why API first?
5. Contentful’s “API-First” Approach 1. Fast 2. Flexible 3. Modern Architecture 1. Fast implementation. Fast performance. - Cloud-native SAAS with CDN - Use the development tools you know - Fast, scalable content migration and transformation using code 2. Build any user experience for any device (anywhere). ‐ A large collection of SDKs ‐ Flexible content models ‐ Designed for easy localization 3. Take advantage of the “modern stack” architecture. - Combine best-of-breed, single purpose apps (micro-services) - Built-in integrations with popular platforms - Connect platforms easily using webhooks and UI extensions
6. APIs allow you to manipulate content with code Content Operations at scale Empowered teams can collaboratively create, curate, and deliver content across channels and campaigns using agile iterative processes. • Independent editorial and development workflows • Continuous Integration / Continuous Deployment (CI/CD) • Refactoring content models • Large-scale content changes
7. How powerful are Contentful’s APIs? Contentful’s web app is built on top of Contentful APIs—anything you can do in the web app (other than billing) you can do with your own code
8. CO N TEN TFUL Contentful is developer-friendly Most stars on Most stacks on Most examples on Compared to other content infrastructure vendors: API Providers with the most SDK listings 125 100 75 50 25 0 Number of SDKs G O O G LE M ICRO SO FT M APBO X PAYPAL AM AZO N M YW AKES D O CO M O SYSTRAN IBM SALESFO RCE BUG SN AG M ERCAD O LIBRE BO X API.AI Source: Programmable Web
9. 9 2. Content delivery architectures
10. Where and when does rendering happen? 1 2 3 Dynamic on Server Static Site Generator Dynamic on Device A client-side app using the Contentful SDKs requests content from the Contentful APIs and renders the content on the device. A server-side app receives a request from an end user, retrieves content from Contentful (and possibly other data sources), renders the content, and sends it back in response. A static site generator fetches content from Contentful at timed intervals or on content change webhook then builds the rendered HTML pages and stores them on a static web host.
11. Dynamic on Server Server-Side Application, iPaaS (Integration Platform as a Service)
12. Dynamic on Server Contentful CDN Your CDN Your Server App
13. Pros • Lots of languages & framework options • Reactive – no stale data • Easier SEO • Secure secrets (API tokens not exposed to end-users) Cons • Server-related scalability ($$$) • Higher page latency • Requires external caching or CDN • Potential single point of failure Dynamic on Server
14. Static Site Generator Jekyll, Next, Hugo, Gatsby, Metalsmith, Middleman, Wyam, etc.
15. Static Site Generator (SSG) 1. Code or content changes trigger webhook to generate static site -OR- Generation triggered on set interval (hourly, daily, etc.) BUILD TIME REQUEST TIME
16. Pros • Easier SEO • Offline capability • Static HTML is fast and simple to serve • Secure secrets (API tokens not exposed to end-users) Cons • No immediate preview/potential for stale data • Web page-centric • Generation time can be problematic for frequent content changes • Requires external hosting, caching, and CDN Static Site Generator (SSG)
17. Dynamic on Device Single Page Application, Native App, Mobile (iOS/Android) App
18. Dynamic on Device Static Host / App Store
19. Pros • Simple • Reactive – no stale data • Fully leverages the Contentful CDN Cons • SEO support requires more effort • Possible browser compatibility issues Dynamic on Device
20. Delivery Models: Pros & Cons Dynamic on Server Static Site Generator Dynamic on Device Dynamic content • • • Page latency • • • App server load • • • SEO • • • Secure Secrets • • • Contentful CDN • • • Availability • • •
21. 21 3. Contentful Core APIs
22. Content Management API Read/Write Create, edit, publish, unpublish, archive, and delete content and content model Content Preview API Read-only Retrieve draft and updated content in addition to published content Content Delivery API Read-only Retrieve published content to display in an app or website Images API Read-only Retrieve and apply transformations to images stored in Contentful Contentful Core APIs
23. Contentful is Content Infrastructure Content Creator Content Delivery API CLI Web App Content Management API SDK SDK SDK Apps & Websites Conversational & Wearables Apps & AR/VR Powerful CLI and tooling to integrate into existing developer workflows or to help define brand new workflows The APIs, webhooks and SDK’s developers need to power content in any digital product. Content Preview API Customizable web app for marketers and publishers to collaborate and create content. Developer Images API
24. The API for managing content on Contentful • Read/Write – You can modify content programmatically and refactor the content model • Enables CI/CD – Allows you to easily move content between spaces using scripts • No CDN – Calls to this API are not cached, so you get and edit the most up-to-date content Content Management API
25. Details Contentful’s Content Management API (CMA) helps you manage content in your spaces. This is a read/write API API Base URL https://api.contentful.com Content Management API
26. Updating Content Take in consideration that Contentful does not merges changes made to content, so when updating content, you need to send the entire body of an entry. If you update content with a subset of properties, you will lose all existing properties not included in that update. You should always update resources in the following order: - Fetch current resource. - Make changes to the current resource. - Update the resource by passing the changed resource along with current version number. Content Management API
27. Example Create a single entry - Request PUT /spaces/yadj1kx9rmg0/environments/staging/entries/post0001 - Headers - Authorization CFPAT-12345... - Content-Type application/vnd.contentful.management.v1+json - X-Contentful-Content-Type blogPost - Parameters - space_id yadj1kx9rmg0 - environment_id staging - entry_id post0001 More details Get a single entry Content Management API
28. Example Create a single entry - Body More details Get a single entry Content Management API { "fields": { "title": { "en-US": "Hello, World!" }, "body": { "en-US": "Welcome to our webinar!" } } }
29. Example Create a single entry - Response (201 Created) More details Get a single entry Content Management API { "sys": { "id": "post001", "type": "Entry", "contentType": { "sys": { "type": "Link", "linkType": "ContentType", "id": "blogPost" }}, "version": 1, "space": { "sys": { "type": "Link", "linkType": "Space", "id": "yadj1kx9rmg0" }}, "environment": { "sys": { "type": "Link", "linkType": "Environment", "id": "staging" }}, "createdAt": "2019-02-18T11:29:46.809Z", "createdBy": {"sys": {"type": "Link","linkType":... "updatedAt": "2019-02-18T11:29:46.809Z", "updatedBy": {"sys": {"type": "Link","linkType":... }, "fields": { "title": { "en-US": "Hello, World!" }, "body": { "en-US": "Welcome to our webinar!" } } }
30. Same functionality as the Content Delivery API except it allows access to both published and unpublished content • Editorial Preview – powers a preview deploy/version of your frontend to allow content editors to see their content exactly as it will look when published • Read Only – You can’t accidently change content • No CDN – Calls to this API are not cached so preview will always have the most up-to-date content Content Preview API
31. Content Preview API Details In addition to the Content Delivery API (CDA) for published content, the Preview API is for previewing unpublished content as though it were published. It maintains the same endpoints and parameters as the CDA, but delivers the latest draft, updated, and published entries and assets. This is a read-only API API Base URL https://preview.contentful.com Learn more about the Preview API
32. The primary API for incorporating Contentful content in your front-end • Read Only – You can’t accidently change content • Published Only – You can’t accidentally reveal unpublished content • CDN – Calls to this API take advantage of the Contentful CDN Content Delivery API
33. Details The Content Delivery API (CDA) is a highly available, highly scalable, read-only API for delivering content to apps, websites, and other channels. This API is available via a globally distributed content delivery network (CDN) API Base URL https://cdn.contentful.com Content Delivery API
34. Example Get a single entry - Request GET /spaces/yadj1kx9rmg0/environments/staging/entries /5KsDBWseXY6QegucYAoacS?access_token=fdb4e7a3102747a02 ea69ebac5e282b9e44d28fb340f778a4f5e788625a61abe - Parameters - space_id yadj1kx9rmg0 - environment_id staging - entry_id 5KsDBWseXY6QegucYAoacS - access_token fdb4e7a3102747a02ea69ebac5e282b9e44 d28fb340f778a4f5e788625a61abe Content Delivery API More details Get a single entry
35. Content Delivery API Example Get a single entry - Response (200 OK) { "sys": { "space": { "sys": { "type": "Link", "linkType": "Space", "id": "yadj1kx9rmg0" } }, "id": "5KsDBWseXY6QegucYAoacS", "type": "Entry", "createdAt": "2017-02-20T17:18:50.583Z", "updatedAt": "2017-02-21T14:29:11.733Z", "environment": { "sys": { "id": "staging", "type": "Link", "linkType": "Environment" } }, "revision": 2, "contentType": { "sys": { "type": "Link", ... "locale": "en-US" }, "fields": { "productName": "Playsam Streamliner Classic Car ... "slug": "playsam-streamliner-classic-car-espresso", "productDescription": "A classic Playsam design ... "image": [{ "sys": { "type": "Link", "linkType" ... "tags": [ "wood", "toy", "car", "sweden", "desi ... "categories": [{ "sys": { "type": "Link","linkT ... "price": 44, "website": "http://www.amazon.com/dp/B001R6JUZ2/" ... More details Get a single entry
36. Allows you to store a single high quality image in Contentful and resize or transform it at delivery time to match the size & quality needed for the requesting device • Read Only – You can’t accidently change content • CDN – Calls to this API take advantage of the Contentful CDN Images API
37. Images API Details The Contentful Images API allows the retrieval and manipulation of image files referenced from assets. In other words, the Images API allows you to resize and crop images, change their background color and convert them to different formats Upload high-quality assets, deliver exactly what your app needs and still get all the benefits of our caching CDN API Base URL https://images.ctfassets.net
38. Example - Changing formats Image format - Request GET /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc06 0607df0f3baef/quwowooybuqbl6ntboz3.jpg?fm=png - Parameters - space_id yadj1kx9rmg0 - asset_id wtrHxeu3zEoEce2MokCSi - token cf6f68efdcf625fdc060607df0f3baef - filename quwowooybuqbl6ntboz3.jpg - image_format fm=png - Response (200 OK) Images API More details Image format
39. More details Specify width & height Images API Example - Resizing & Cropping Specify width & height - Request GET /yadj1kx9rmg0/wtrHxeu3zEoEce2MokCSi/cf6f68efdcf625fdc06 0607df0f3baef/quwowooybuqbl6ntboz3.jpg?w=800&h=600 - Parameters - space_id yadj1kx9rmg0 - asset_id wtrHxeu3zEoEce2MokCSi - token cf6f68efdcf625fdc060607df0f3baef - filename quwowooybuqbl6ntboz3.jpg - width w=800 - height h=600 - Response (200 OK)
40. 40 4. SDKs
41. SDKs Supported Platforms
42. Platforms hold all SDKs, Tutorials, Demos, Sample apps and Integrations for different programming languages. - Javascript - PHP - Android - iOS - Swift - Java - Python - Ruby - .Net SDKs
43. 43 5. GraphQL Content API
44. What is GraphQL • It is an open-source data query and manipulation language for APIs, and a runtime for fulfilling queries with existing data • It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server, therefore preventing excessively large amounts of data from being returned • GraphQL schemas are strongly typed - reliably know what type of data is where
45. • It provides a GraphQL interface to the content from Contentful. • Each space has a GraphQL schema based on its content model. The schema is generated at request time so it is always current. • You can use this API to consume both published and unpublished content. • There is query complexity limit currently set to allow retrieval of 11,000 entities in one request • This API supports schema stitching which allows two or more GraphQL APIs to be combined into a single schema that can be presented to a client application GraphQL Content API
46. Small GraphQL vs. Big REST Rest API call: curl -X GET --header "Accept: application/json" --header "Authorization: Bearer ..." "https://api.deutschebahn.com/fasta/v2/stations/1866" GraphQL API call: curl -X POST --header "Content-Type: application/json" --header "Authorization: Bearer ..." -d '{"query": "{stationWithStationNumber(stationNumber: 1866){facilities{type description} }}"}' https://bahnql.herokuapp.com/graphql query{ stationWithStationNumber(stationNumber: 1866){ facilities{ type description } } }
47. Rest API call: curl -X GET --header "Accept: application/json" --header "Authorization: Bearer ..." "https://api.deutschebahn.com/fasta/v2/stations/1866" GraphQL API call: curl -X POST --header "Content-Type: application/json" --header "Authorization: Bearer ..." -d '{"query": "{stationWithStationNumber(stationNumber: 1866){facilities{type description} }}"}' https://bahnql.herokuapp.com/graphql query{ stationWithStationNumber(stationNumber: 1866){ facilities{ type description } } } Small GraphQL vs. Big REST
48. Small GraphQL vs. Big REST Rest API Response: { "stationnumber": 1866, "name": "Frankfurt (Main) Hbf", "facilities": [ { "equipmentnumber": 10313104, "type": "ESCALATOR", "description": "zu Gleis 103/104 (S-Bahn)", "geocoordX": 8.66231455, "geocoordY": 50.10727055, "state": "INACTIVE", "stateExplanation": "under construction", "stationnumber": 1866 }, { "equipmentnumber": 10313109, "type": "ESCALATOR", "description": "zu Gleis 101/102 (S-Bahn)", "geocoordX": 8.66341625, "geocoordY": 50.1074703, "state": "INACTIVE", "stateExplanation": "under construction", "stationnumber": 1866 }, GraphQL API Response: { "data": { "stationWithEvaId": { "facilities": [ { "type": "ESCALATOR", "description": "zu Gleis 103/104 (S-Bahn)" }, { "type": "ESCALATOR", "description": "zu Gleis 101/102 (S-Bahn)" },
49. BUT... • Caching is very complicated and might impact response time • Errors don't cause an http response code indicating an error (4XX) although Contentful provides very complete and through errors in the standard GraphQL manner
50. Questions Topics 1.The “API first” approach 2.Content delivery architecture 3.Core APIs 4.SDKs 5.GraphQL