Lessons Learned: Using a Headless CMS without an SDK

How complicated is it for a beginner to implement a headless CMS powered site without an SDK? I chose Python and Flask to build a section of a sample site. Did I succeed? And what did I learn in the process?

Why Python and Flask?

Earlier this year, I found myself spending a lot of time manually grinding through administrative tasks that felt repetitive, time consuming, and tedious. I began to search for the best way for a non-developer to start automating tasks. After a few days of browsing, I noticed that I always seemed to end up on a blog, forum, or community post talking about Python. I picked up a few books, took an online introductory course, and started writing scripts to help me with my work.

After completing some basic tutorials, I wondered if I could somehow connect these newly learned skills to the Content-as-a-Service product that my team supports, Kentico Kontent. Furthermore, could I do it without an SDK since Kontent does not currently have one for Python? To test this, I decided to recreate the articles section of the Dancing Goat sample project that comes with new Kontent subscriptions and catalog some of the lessons I learned from the project.

Learn the Terminology

If you've decided to use Kentico Kontent for your project, reviewing and bookmarking the terminology we use throughout the documentation and product UI is an important step. If you're diving into a project and haven't established a firm grasp on the differences between content types, content items, and components, then the Kentico Kontent documentation won’t deliver its true value.

Lesson learned: taking the time to “learn the lingo” makes working in the Kentico Kontent ecosystem easier.

Establish Your Project Scope

Scope creep has always been an issue of mine, and I don't think I'm alone. When I began this project, I naively wanted to recreate the Dancing Goat site in its entirety while leveraging all of Kentico Kontent’s features. This wasn't an effective plan.
Although no Kentico Kontent features are too difficult to implement, starting small and focusing just on the home page and articles in the sample site gave me the best opportunity to learn. I could see the API in action, learn about the Flask microframework, and understand how content modeling was done in the sample project.

Lesson learned: starting small and then scaling up prevents the project from becoming overwhelming and provides the opportunity to learn the Kentico Kontent basics.

Structure Your Content

Knowing how the content types and content items connected to each other in my sample project saved me a significant amount of time. Since mapping out the home page and article relationships was so useful in a pre-generated project, I know it will be even more beneficial for a new project.
I've seen a fair share of real customer projects that have redundant entries because they didn't consider the relationships between their content prior to development. This section on content modeling from the Kentico Kontent documentation will likely be helpful in avoiding this pitfall.

Lesson learned: prevent duplicative content by understanding what is reusable and which content is related.

Create Sample/Starter Content

I remember feeling a bit overwhelmed by the size of the Delivery API responses from my project. This is because I was using the sample site which has a lot of content items and linked items. The sample site is a great reference tool, but may be more complex than most projects need to be.
Building out a minimal set of content types and items related to the core functionality in your project can save time when developing your front-end application. Creating only a few content items in the project will make reading and using the JSON responses provided by the Delivery API more manageable. You'll also have an easier time remembering the codenames of your content items, which you will be using a lot during testing. Keep it simple, then scale up.

Lesson learned: only build a few content items of each type during the early phases of the project to make analyzing JSON responses more straightforward.

Identify the Necessary API Requests

I started using the POSTman REST client to test and document the GET requests I needed to make in my project. This was immensely helpful since I needed to construct requests in my front-end application using a Python library. It can also be helpful in other scenarios since:

1. You'll familiarize yourself with the Delivery API’s response structure.
2. You'll be more aware of the API's filtering capabilities.
3. You can more easily determine if there is an issue with your code, the content, or our API endpoint during debugging. By running tests in a REST client, you separate your code from our product.

Lesson learned: understanding the API calls in advance provides a helpful roadmap for building a front-end application and helps during debugging.

Decide If You Are Going to Use an SDK

I knew there wasn't a Python SDK for Kentico Kontent. I needed to find documentation on how to call API endpoints using Python and Flask. This may not be your situation, but it would be a shame if halfway through a JavaScript, .Net, PHP, Ruby, or Java project, you or your developers stumbled upon an SDK that would have made your lives a lot easier.

For projects that will use an SDK, it is important to review the SDK documentation, stay up to date on current GitHub issue submissions, and check release notes for the chosen SDK. The SDK GitHub repositories and their accompanying documentation are updated frequently, including breaking change documentation when a new version of an SDK is released.

Lesson learned: collect and review relevant documentation before starting your project, and watch the GitHub repositories that you are using for your project.

Understand the Conventions in Your Selected Framework/Programming Language

Let's be honest, I started hacking away trying to get my front-end application to work. The approach should have been to explore Flask and Python conventions first. Understanding what options I had for structuring my application, determining routes, error handling capabilities, and configuration file conventions should have come sooner rather than later in the project.

I'm sure Flask and Python purists could have a field day critiquing my sample project, but when I started applying some conventions, my application started to become more manageable. If I had known this, I could have saved a lot of time!

Lesson learned: learning about framework conventions prior to development makes the project easier to navigate and manage.

Formulate a Resolver Strategy (for Types and Inline Items)

Early on, it was clear that not using strongly typed models made my project very messy and hard to read. Once I implemented my own type helper, similar to the CustomTypeProvider in the Kentico Kontent .Net sample site, I was able to improve the readability of my code. To help with strongly typing models, Kentico created model generators for the .Net, JavaScript, and Java SDKs. This didn't help me with my Python project, but it is good to know that these tools are available for projects that use the SDKs.

In addition to strongly typing models, you'll want to resolve linked items, components, and text links that appear in Rich Text elements. In my project, I had to create a custom resolver. This resolver scrapes the content in my Rich Text elements for object and anchor tags and replaces the references with actual links or content. This seems confusing at first, but after spending some time looking at the JSON returned by the API for individual content items, you'll see that Rich Text elements come with accompanying “links” and “modular_content” values that can be used for inline link and item resolution.

Luckily, the Kentico Kontent documentation has a section on dealing with structure in rich text, and there are built-in methods in the Kentico Kontent SDKs that handle this resolution for the most part. If you decide to use an SDK, a resolver strategy will be more straightforward. Otherwise, spend some time looking at the structure of the API's JSON responses for linked items and rich text.

Lessons learned: plan on implementing strongly typed models from the beginning of the project, and review how inline content items appear in the Delivery API responses.

Start Building

I hope that after reading about the steps that helped me with my project, you feel more prepared to take on a new Kontent project of your own. As a Python and programming novice, I was able to get a Kentico Kontent blog up and running without an SDK, so I am sure you will create some killer apps that enable a flawless content strategy. You can check out my project here on GitHub, and feel free to leave comments and suggestions.
If Vue.js is more interesting or relevant to you, my colleague Chris Jennings also wrote an excellent "Lessons learned" blog post that may be helpful.