Replace a hand-written client

If your site already calls the Content Delivery API with its own fetch code, you do not have to start again to use @ebitex/content-sdk. This page lists what the package does that a hand-written client usually does not, and a path that keeps your renderers and parsers.

If you are starting a site, skip this page and begin with Render content in a static site or Render content on a server. On .NET, the equivalent package is Ebitex.Content.Delivery: see Render content from a .NET server.

What a hand-written client has to keep doing

A client written against the responses seen on one day is correct that day. These are the parts that change under it, or that are easy to miss.

• The endpoints. Path resolution, components, streams and their facets, media, and parsing every response. The package has one method per endpoint and moves with the API.
• The sitemap. buildSitemapDocuments shards at the protocol limits, writes an index, and emits hreflang alternates when you give it a localeUrl. A sitemap built by hand rarely does any of the three, and robots.txt built by joining strings can produce an address like //sitemap.xml.
• Live preview and click-to-edit. The preview bridge needs the annotated responses of a preview session. A client that reads only the fields it renders discards the annotations, so the editor has nothing to point at. Nothing fails; the feature is just absent.
• Locale addressing. Under the path-prefix and locale-host strategies, every address the API returns already carries its language. A client that adds its own /${locale} prefix doubles it, and one that assumes a prefix on a site with none links its home page to a missing page. See Localization.
• Caching and invalidation. What may be cached, under which key, and what a publish should clear. See Caching.
• References. A delivered Presentation is usually a reference. A renderer that does not ask the API to resolve it renders an empty page.

Move over in steps

1. Install the package and create a client with the key you already use.
2. Replace your fetch calls with the client’s methods, one endpoint at a time. The responses are the API’s own, so the code that reads them keeps working while you do.
3. If the site’s locale addressing is not invariant, remove any locale prefix your code adds.
4. Replace your sitemap and robots code with buildSitemapDocuments.
5. Add the preview bridge and have your preview route use a preview session.
6. Delete the old client and its tests.