Working with Crafter Studio?s API

CrafterCMS 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:

  • Authenticate
  • 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 CrafterCMS version 3.0 here
http://docs.craftercms.org/en/3.0/developers/projects/studio/api/index.html

Step 1: Authenticate

We’ll use the authenticate API
http://docs.craftercms.org/en/3.0/developers/projects/studio/api/security/login.html

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

http://docs.craftercms.org/en/3.0/developers/projects/studio/api/content/write-content.html

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 CrafterCMS where and how to store the content in the repository

Conclusion

In this article we covered the basic mechanics of connecting to and interacting with Crafter Studio, the authoring services of CrafterCMS.  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!