# Content delivery API in Umbraco 12 RC 1 - Did I say Headless? Umbraco 12 Release Candidate 1 was released yesterday, 17 May 2023. There were quite a few features in this release as described in the [release notes](https://umbraco.com/blog/umbraco-12-release-candidate). But what I was most excited about was the Content Delivery API. As a member of the [Umbraco Headless Community Team](https://umbraco.com/blog/meet-the-headless-community-team/), I was aware of this and we as a team had made several suggestions on the direction of this feature. # Documentation The official [Content Delivery API](https://docs.umbraco.com/umbraco-cms/v/12.latest/reference/content-delivery-api) documentation is pretty comprehensive and is a good place to start. # Installing 12RC1 on your local machine If you want to try it out on your local machine, the [Package Script Writer](https://psw.codeshare.co.uk/?InstallUmbracoTemplate=true&UmbracoTemplateVersion=12.0.0-rc1&Packages=&UserEmail=admin%40example.com&ProjectName=MyProject&CreateSolutionFile=true&SolutionName=MySolution&UseUnattendedInstall=true&DatabaseType=SQLite&UserPassword=1234567890&UserFriendlyName=Administrator&IncludeStarterKit=true&StarterKitPackage=Umbraco.TheStarterKit&OnelinerOutput=false) by Paul Seal is an excellent resource. Within a few minutes, you will have Umbraco 12 RC 1 installed and ready to test out on your local machine. # Installing 12RC1 on an Azure Web App But of course, I wanted to try this out on Azure and share it with the devs at Luminary. I've got this nifty script that I run on an Azure Cloud Shell. In around 20 minutes I get a fully functional Umbraco 12 RC 1 with the Content Delivery API enabled. ```bash wget https://www.speedycmsinstall.com/scripts/azure/v12rc1/create-umbraco-v12rc1-demo.sh chmod +x create-umbraco-v12rc1-demo.sh ./create-umbraco-v12rc1-demo.sh ``` *You can fork the bash script from* [*GitHub*](https://github.com/emmanueltissera/speedycmsinstall/tree/main/scripts/azure/v12rc1) *and tinker with it for your own needs. If you need more details on this script, you can read all about it in* [*Scripting an Azure deployment of Umbraco 9*](https://archive.24days.in/umbraco-cms/2021/scripting-azure-deployment/)*.* ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1684409299455/2f1dc0c1-d2fc-4b04-b055-8c8395ca8130.png align="center") ## Starter Kit installed My bash script also installed the "Starter Kit" which gave me some content to play with while testing out the new Content Delivery API. # Trying out the Content Delivery API I tried the most obvious choices for testing out the content delivery API. Note that the following URLs may not work in the future as this test environment is ephemeral. ## Retrieving all the content Retrieving all the content was easy enough. ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net/umbraco/delivery/api/v1/content" ``` But it seemed I was missing something. I know that my name was included in this Starter Kit. But the Delivery API did not return that item to me. ```json { "total": 30, "items": [ { "name": "Home", "route": { "path": "/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "contentType": "home", "properties": { "heroHeader": "Umbraco Demo", // removed for brevity }, "cultures": {} }, { "name": "Products", // removed for brevity }, // removed for brevity { // item #10 "name": "Biker Jacket", // removed for brevity } ] } ``` Since it said that there were 30 items in total, I tried the `take` query parameter as follows: ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net/umbraco/delivery/api/v1/content?take=30" ``` Voila! I can now see 30 items and myself in the JSON results. ```json { "total": 30, "items": [ { "name": "Home", // removed for brevity }, // removed for brevity { "name": "People", // removed for brevity }, // removed for brevity { "name": "Emmanuel Tissera", "route": { "path": "/people/emmanuel-tissera/", // removed for brevity }, "id": "6374bda9-034a-4109-a837-72ed6a325f11", "contentType": "person", "properties": { "seoMetaDescription": "", "keywords": [], "umbracoNavihide": false, "photo": [ { "id": "77db56ab-2f79-4eb2-82fd-eb7266e6b366", "name": "Emmanuel Tissera", "mediaType": "Image", "url": "/media/vvlnw31z/emmanuel_tissera.jpg", "extension": "jpg", "width": 1600, "height": 1200, "bytes": 772875, "properties": {}, "focalPoint": null, "crops": [] } ], "department": [ "Australia", "mvp" ], "email": "", "twitterUsername": "", "facebookUsername": "", "linkedInUsername": "", "instagramUsername": "" }, "cultures": {} }, // removed for brevity { // Item #30 "name": "Contact", // removed for brevity } ] } ``` ⚠️ I believe the Content Delivery API is missing a pagination block to let consumers know how many records have been returned and how they should reach for the next set. ## Retrieve a particular item via ID Request: ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net/umbraco/delivery/api/v1/content/item/6374bda9-034a-4109-a837-72ed6a325f11" ``` Response: ```json { "name": "Emmanuel Tissera", "route": { "path": "/people/emmanuel-tissera/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, "id": "6374bda9-034a-4109-a837-72ed6a325f11", "contentType": "person", "properties": { "seoMetaDescription": "", "keywords": [], "umbracoNavihide": false, "photo": [ { "id": "77db56ab-2f79-4eb2-82fd-eb7266e6b366", "name": "Emmanuel Tissera", "mediaType": "Image", "url": "/media/vvlnw31z/emmanuel_tissera.jpg", "extension": "jpg", "width": 1600, "height": 1200, "bytes": 772875, "properties": {}, "focalPoint": null, "crops": [] } ], "department": [ "Australia", "mvp" ], "email": "", "twitterUsername": "", "facebookUsername": "", "linkedInUsername": "", "instagramUsername": "" }, "cultures": {} } ``` 🌟Worked as expected. ## Retrieve a particular item via Path Request: ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net/umbraco/delivery/api/v1/content/item/people/emmanuel-tissera" ``` Response: ```json { "name": "Emmanuel Tissera", "route": { "path": "/people/emmanuel-tissera/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, // removed for brevity - same as above } ``` 💪Worked as expected and I just needed to only know the path of the content item I was hoping to retrieve. ## Retrieve draft/preview content There are times when you need to preview draft content and the Content Delivery API does a great job with this. ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net//umbraco/delivery/api/v1/content/item/6374bda9-034a-4109-a837-72ed6a325f11" --header "Preview: true" --header "Api-Key: my-secret" ``` Response: ```json { "name": "Emm Tissera", "route": { "path": "/people/emmanuel-tissera/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, // removed for brevity "properties": { // removed for brevity "email": "", "twitterUsername": "dAmazingNut", "facebookUsername": "", "linkedInUsername": "", "instagramUsername": "" }, "cultures": {} } ``` 👀As you can see there is preview content where I have changed the name of the content item and added a `twitterUsername`. These changes are not visible on the public API. ## Adding a new Document Type To just test how easy this was, I added a new Document Type called `Pet`. I populated the details of my two dogs and made this request. ```bash curl --location "https://umbracov12rc1-demo-19175.azurewebsites.net//umbraco/delivery/api/v1/content/?filter=contentType:pet" ``` Without writing a single line of code in the CMS back office, I get this JSON response. ```json { "total": 2, "items": [ { "name": "Shadow", "route": { "path": "/people/shadow/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, "id": "2b9116f6-a45f-404d-8ef2-64900148eca9", "contentType": "pet", "properties": { "petName": "Shadow", "breed": "Staffie", "isCuddley": true, "dateOfBirth": "2016-10-11T00:00:00Z" }, "cultures": {} }, { "name": "Athena", "route": { "path": "/people/athena/", "startItem": { "id": "ca4249ed-2b23-4337-b522-63cabe5587d1", "path": "home" } }, "id": "64bf848f-06f3-4856-b730-84d4dbbeab08", "contentType": "pet", "properties": { "petName": "Athena", "breed": "Staffie", "isCuddley": true, "dateOfBirth": "2019-02-11T00:00:00Z" }, "cultures": {} } ] } ``` # The Verdict That was a quick whirlwind tour of the new Umbraco Content Delivery API which is a part of the core offering and I'm loving it. I need to explore the localisation features and see if it passes my [GILT or GUILT – Localisation crimes](https://emmti.com/gilt-or-guilt-localisation-crimes) test. I couldn't see the swagger documentation on Azure and that's something I will explore further. The team working on the Content Delivery API have done a great job in the first release candidate and I'm hoping they will fix the [current limitations](https://docs.umbraco.com/umbraco-cms/v/12.latest/reference/content-delivery-api#current-limitations) they have listed to make this product shine. ## Provide your own feedback If you find issues that are not already [reported](https://github.com/umbraco/Umbraco-CMS/issues?q=is%3Aopen+is%3Aissue+label%3Aaffected%2Fv12), please report them on the [GitHub tracker](https://github.com/umbraco/Umbraco-CMS/issues/new?assignees=&labels=type%2Fbug&template=01_bug_report.yml&title=v12%20RC1) by following the link or selecting “🐛 Bug Report” when creating a new issue. That reminds me that I should file a suggestion for that pagination issue I encountered. # Public release I'm looking forward to the public release of Umbraco 12, which is targeted for June 29, 2023. # The Possibilities With the Content Delivery API in place, a developer could create new Document types and have Content Authors editing adding and updating content even before the front-end has been built. This allows for a composable architecture where the content is just another API. With the Content Delivery API in place, Umbraco has placed itself in a strong position in that hybrid headless space.