Content Management API — give us feedback

TomasHrubyTomasHruby Member, Kentico Staff mod
edited July 2017 in General

I'm delighted to have the opportunity to get your feedback again. We're on the verge of implementing Content Management API and as usual, we would like to get your feedback. Since we're developing Kentico Cloud to make you more productive, our team came up with the idea of sharing our current API design with you.

Let me start with our development plans. Content Management API is a huge topic, and it covers various development needs. We're up to starting with the most popular one now (see the list below) and continue improving Content Management API in future milestones. You can read what we're up to next, before improving CM API in our roadmap. For the following jobs is Content Management API crucial:

  • Importing content using API. This one is the most popular and will be implemented first.
  • Let users manage content in your app.
  • Integrate 3rd party service using API

Endpoints

Now, let's dive into the API specs. From the high-level perspective, we're going to implement the following API endpoints:

  • (POST) Create content items
  • (PUT) Update content items
  • (DELETE) Delete existing content items
  • (POST) Upload new assets
  • (PUT) Update asset description
  • (DELETE) Delete existing assets

When calling the API, it will respond with operation status code (e.g. 201 Created) and created/updated object in the response body (see model specs below). If the call fails, the API will respond with error status code (e.g. 400 Bad Request) and an actionable comment that should get you back on track quickly.

Notice, that the API doesn't support creating and updating content types or taxonomy. Although this might be required when building integration, for the most crucial task — importing content it might not be necessary.

Model

Moving on to the content model, you'll be able to add content items into the request body in the following format:

{
  "system": {
    "name": "On Roasts",
    "type": "article",
    "sitemap_locations": [
      "articles"
    ],
  },
  "elements": {
    // Text
    "title": {
      "value": "Awesome article"
    },
    // Rich text
    "description": {
      "value": "<p>We operate our own roasteries, one on every continent we cover, from where we distribute right to the shops.</p>"
    },
    // Multiple choice
    "processing": {
      "value": [
        "dry__natural_"
      ]
    },
    // Number
    "price": {
      "value": 8.5
    },
    // Date
    "post_date": {
      "value": "2014-11-18T00:00:00Z"
    },
    // Asset
    "teaser_image": {
      "value": [
        "296aa91a-6bc0-424e-bd8f-778a9de62065"
      ]
    },
    // Modular content
    "facts": {
      "value": [
        "our_philosophy",
        "how_we_source_our_coffees",
        "how_we_roast_our_coffees"
      ]
    },
    // Taxonomy
    "personas": {
      "value": [
        "coffee_lover"
      ]
    },
    // Custom URL slug
    "url_slug": {
      "value": "brazil-natural-barra-grande"
    }
  }
}

To summarize the content model, you'll be able to create any structured content with the new API. Since the existing content might not cover all content elements, you can leave some elements from the import request. This is particularly useful for URL slug element, which is commonly auto-generated. System fields such as ID or codename are going to be automatically generated by us as well.

Apart from creating content items, you can connect items to other objects such as Taxonomy terms, Sitemap locations, Modular content or Assets. For most objects, you can simply provide their codename in e.g. Taxonomy element value. Assets are an exception. You'll need to use the Asset endpoint to upload assets first and then connect them with content items. After upload, the Asset endpoint returns asset ID which you can add to asset element value to link it to a content item.

Limitations

You may be wondering how to insert inline images, content modules within a rich text or how you can link another content item from within a rich text. Unfortunately, as for the first version, you can only manage basic rich text supported by Kentico Cloud UI such as headings, paragraphs or links to the web. We know inline objects are widely used in content production, but there are a few reasons, why we decided to release the CM API without supporting inline objects:

  • Apart from CM API, we have a lot of popular feature request that will make you more productive.
  • The main driver for CM API is importing existing content and we're not sure how many projects contain existing content with inline images.
  • We weren't sure how you would deal with importing content links from old environment to Kentico Cloud. Such links might for example point to old URLs.
  • Let's call modular content a Kentico Cloud specific feature. We were not sure how you would utilize them in existing content import.

To sum up, for most import scenarios, inline objects in a rich text shouldn't be required. On the other hand, they might be required when using the CM API for integrations. And, as I mentioned earlier, we plan to improve the CM API over time.

Authentication

Compared to Delivery API, enabling the Content Management API might be a security risk. Similarly to the Preview API, you are going to be able to generate an API key or turn the CM API off completely.

Summary

To sum up, you've read what the first version of the CM API will look like. We're here to listen to you, so don't hesitate to send us your honest feedback (bluntly it's even better). Leave a comment here or let me know when you're free and we can schedule a call.

Thanks in advance for your valuable feedback.

Comments

  • LeeConlinLeeConlin Member ✭✭

    Let me take each of the "limitations" and respond.

    Inline images
    The ability to use inline images is an absolute must-have for all 3 use-cases you describe.

    I'd envision this working using two API calls. 1 to upload the image and retrieve the uploaded objects ID, then the second would be to save the content item. The image would be added to the content item's rich_text in a similar way to how it would be stored in the inventory, as an image tag with a data-attribute.

    Content links
    Linking to other pages I've created in any of the three use-cases is another must-have.

    I'd envision it working in a similar way to images as described above. Except that the data-attribute could carry the content items code_name instead. In this way you could create links to potentially non-existant content items during import where you know what the code_name will be when the import gets that far.

    Inline modular content
    This one is not as much a must-have, but rather it would be very useful.

    Again, it could be done simply as a special snippet in the rich-text that gets parsed out by your API and uses the code_name of a content item (or items) to be placed in that location.

    Will your .Net SDK be updated to allow use of the write API?

  • TomasHrubyTomasHruby Member, Kentico Staff mod

    Ok, so if I understand it correctly, inline images and content links are an absolute must-have even for importing existing content to Kentico Cloud. First of all, thanks for that feedback, because we still can update what we're going to implement.

    Anyway, one of the reasons why we chose to postpone this was that the feedback we got, wasn't consistent in the fact that existing content that you need to import to Kentico Cloud contains inline images and content links. I guess that the main reason is that you need to get the existing content somehow, e.g. by exporting content from the previous CMS. Exporting structured content is easy, but exporting whole pages might be difficult because the content is often embedded in front-end code.

    From your experience, @LeeConlin is migrating existing content something you do regularly?

    • If yes, does it contain inline images and content links?
    • And, how do you extract that content from the existing environment?
  • LeeConlinLeeConlin Member ✭✭
    edited July 2017

    @TomasHruby Yes, I do it more often than I would like in truth and it's always a difficult process.

    Typically it involves either exporting the content from an existing CMS, reading a database directly or sometimes even scraping an existing site.

    In all cases one thing remains constant - the need to parse the HTML content for links and images and import them, updating them inline on the fly to meet the requirements of the new site/system.

    I find myself often using HTMLAgilityPack in c# to do this with Kentico CMS. The last one I did was a Wordpress blog into a larger Kentico EMS site.

    It involved parsing the Wordpress pages, making separate WebClient requests for each inline image which are downloaded into a byte[] and deposited directly into the Kentico media library, which then provides a URL to the image that can replace the original URL in the content piece's HTML.

    The same would be true for links, except in this case the order in which content was imported would have to be managed or I'd have to be able to predict the URL structure after import in order to transform the embedded link URLs.

    Hope this helps.

  • TomasHrubyTomasHruby Member, Kentico Staff mod

    Thanks for your help, @LeeConlin . Hopefully, we'll manage to implement inline objects into the initial release.

    Regarding your request about SDK, most probably, we're going to release a separate CM API SDK so that you don't need to use the web client directly. We haven't designed it yet, but IMHO we're going to add typed models and the few methods mentioned above. However, let us know what are your expectations. How would you imagine the .NET SDK for the CM API?

  • LeeConlinLeeConlin Member ✭✭

    My first thought on it would be "Will it support my strongly typed models?" ... if you're advocating the use of strongly typed models for the delivery API SDK then the CM API should support them as well.

    That said, it should also be able to handle a normal "ContentItem" as well... which may mean updating the ContentItem class with setters and a public constructor.

    Sharing the strongly typed objects, ContentItem and other classes such as the type resolvers, etc. between the two SDKs seems sensible in this case.

  • TomasHrubyTomasHruby Member, Kentico Staff mod

    @LeeConlin We've added inline images, inline modular content and content links to the MVP scope of CM API. Thanks for helping us realize that!

    Briefly, when importing you'll be able to insert e.g. inline modular content that doesn't exist in the inventory. You would reference it either with our or external ID. So, every object in CM API can be identified using an external identifier which could be an ID from the old system. It is internally translated to our identifier (GUID). To wrap up, you'll be able to import everything in one go. Naturally, some referenced object might stay inconsistent, for that reason we plan to add an endpoint that would list you all inconsistencies in the project (e.g. non-existent referenced objects)

    Therefore, when it comes to typed model, it could be a little bit different from the Delivery API, but I agree that generating models the similar way for the CM API would save you manual work. We plan to add it in the MVP as well.

  • LeeConlinLeeConlin Member ✭✭

    I've had a good think about everything said in this thread and one more thing comes to mind... the ability to create/update/delete Content Types.

    If I'm building a .NET MVC website from scratch I might want to build it against a "dev" version of content - a different Kentico Cloud account - and have the content type creation done in code so that the content items are created when the application starts up.

    This would be useful for a template solution where I could have a set of standard content types that I use on every project - thus I code them into the solution. "Navigation Item" for example (from your own example project) would be a great use-case for this.

  • JanLenochJanLenoch Czech RepublicMember, Administrator, Kentico Staff admin

    Hello @LeeConlin , I've seen the exact same requirement in our product board and I've added a reference to your one. The story will get some more importance. Thanks for letting us know!

  • TomasHrubyTomasHruby Member, Kentico Staff mod

    Good point, @LeeConlin . The CM API is already in development (actually, we plan to release BETA in two weeks). I believe that this will be one of the improvements we will consider. So, I see two use-cases in your comment:

    • Creating a set of commonly used content types automatically. Could you think of any other examples than navigation items?
    • Creating a development version of website/app. Could you please tell me more about what your development process looks like?
      ** How often do you spin-off a development instance?
      ** How do you synchronize changes between development and production?
  • LeeConlinLeeConlin Member ✭✭

    @TomasHruby

    Creating a set of commonly used content types automatically. Could you think of any other examples than navigation items?

    Within the context of a base/boilerplate app, you might want to include standard content types such as "Page" and "Article" that you use in most projects.

    Within an actual project though, you could use this feature to programmatically ensure the presence of all content types that your project uses. This would be useful when moving between environments as new content types can be added in dev and you can be certain that once the code is pointed at the live project in KC that the content types will be created.

    How often do you spin-off a development instance?
    How do you synchronize changes between development and production?

    I'm used to developing on other platforms such as Pantheon (Wordpress) and Umbraco Cloud - both of which offer multiple environments and provide tools for synchronising both code and content between each environment.

    With Kentico Cloud I would like to have two projects minimum per actual site. One would be for development and my local .net solution would point at this one.

    The other would be the live project and the deployed & live solution would point at that one.

    Having a way of natively syncing content back from live to dev would be nice, but not essential in relation to this feature.

    The main issue is the creation of the content types... being able to automate that is a step towards multi-environment development setups.

    I would envision having a service that runs on startup in my solution that would check for the existence of a list of content types ... if found, it would check the elements defined on them and ensure that the definition matched the coded definition. If not found they would be created.

    Hope this helps.

  • TomasHrubyTomasHruby Member, Kentico Staff mod
    edited November 2017

    Thank you all for providing brilliant feedback!

    We are now working hard on implementing the CM API to Kentico Cloud. Thanks to your feedback, @LeeConlin, and voice of many other developers, we realized that manipulating modular content and rich text is an integral part of the import process. You might have already noticed that the BETA version of the CM API is already out, meaning you can use it in your project. I encourage you to go for it and again, give us your honest feedback. We're going to finalize the documentation as we go, but the CM API is going to be ready by the end of the year.

    There are few important limitations you should know and which mean potential improvements for Kentico Cloud team:

    • CM API key is personal and limited. The API key is unique for every user and expires in 3 months, which should be enough for the import process, but is not for an on-going integration. Please tell us if you're one of the people you care about adding support for permanent API keys.
    • CM API allows you to import only content. Content models such as types or taxonomy can't currently be created or updated using API. We got some feedback that some developers would use the API to add "boilerplate types" to a project. However, also non-technical roles crave for this feature and we're still considering whether to build a UI feature on top of our internal API, or, add this to CM API. The second most frequent feedback is migrating content types between environments. If you believe this is important, please drop me an email and I'll be happy to discuss this (and share our plans with you).
Sign In or Register to comment.