Working with Crafter Studio’s API
Crafter CMS is a decoupled CMS composed multiple microservices where content authoring and content delivery capabilities and services are separated into their own distinct, subsystems.
Organizations often want to interact with the content authoring and management system via APIs. In this article, we’ll show the basics of interacting with this API by example:
- Get a list of projects under management
- Write content to a project
To keep things really basic, we’ll use CURL, a ubiquitous Linux command tool as our client.
You can find the full Crafter Studio API for Crafter CMS version 3.0 here
Step 1: Authenticate
We’ll use the authenticate API
The first thing you’ll note is that we’re going to perform a POST, passing the username and password as a JSON object. In a production environment, you will want to use HTTPS.
The next thing you will notice, we are passing a cookie “XSRF-TOKEN” and a header “X-XSRF-TOKEN”. The value passed for these are arbitrary. They must match and they must be passed in all future PUT and POST API calls. These are used to protect against certain cross-browser scripting attacks. If you are using Studio APIs as part of a web client you want to make sure these values randomly generated.
When you issue the curl command you will get back a response:
Note the response returned is a successful 200 status code and the response contains JSON with details for the authenticated user.
Also found as part of the request is the JSESSION cookie. You will need this value for all future requests.
Step 2: Get a list of sites the user is authorized to work with
http://docs.craftercms.org/en/3.0/developers/projects/studio/api/site/get-sites-per-user.html Note the CURL command contains your session ID and XSRF tokens.
When you issue the CURL you will get a response that contains sites your user has access to:
The response above contains a number of projects. In the next call I want to write a content object to one of the projects (editorial.com.) To do this I need the site ID. I get this from the response above: editorialcom
Step 3: Write content to the Editorial com Project
In the call above note:
- We are passing in content as the POST body. The content is in XML format. In Crafter content objects are stored as simple XML documents.
- We are passing the Session ID and the XSRF tokens
- We are passing a number of parameters that tell Crafter CMS where and how to store the content in the repository
In this article we covered the basic mechanics of connecting to and interacting with Crafter Studio, the authoring services of Crafter CMS. We’ve avoided the nitty gritty details of each API call in favor of the macro mechanics. You now have the basic skills and capability to interact with any Crafter Studio API found here: http://docs.craftercms.org/en/3.0/developers/projects/studio/api/index.html. Get out there and integrate!
Russ Danner is VP Products at Crafter Software and is responsible for product management, product development and support, and client and partner success. Russ brings over 20 years of software architecture, design, and implementation experience. Prior to Crafter Software, Russ was Web Experience Management Practice Director at Rivet Logic and project lead for the open source Crafter CMS project.