Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Working With Crafter Studio's API

DZone's Guide to

Working With Crafter Studio's API

In this article, we look at how organizations can interact with their CMS's content authoring and management system via APIs.

· Web Dev Zone ·
Free Resource

Bugsnag monitors application stability, so you can make data-driven decisions on whether you should be building new features, or fixing bugs. Learn more.

Crafter CMS is a decoupled CMS composed of 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:

  • Authentication.
  • 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: Authentication

We'll use the authentication API.

curl -d '{"username":"admin","password":"admin"}' --cookie "XSRF-TOKEN=A_VALUE" --header "X-XSRF-TOKEN:A_VALUE" --header "Content-Type: application/json" -v -X POST http://localhost:8080/studio/api/1/services/api/1/security/login.json

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 is that we are passing a cookie "XSRF-TOKEN" and a header "X-XSRF-TOKEN." The values 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 are randomly generated.

When you issue the curl command you will get back a response:
 * Trying ::1...
 * Trying 127.0.0.1...
 * Connected to localhost (127.0.0.1) port 8080 (#0)
 > POST /studio/api/1/services/api/1/security/login.json HTTP/1.1
 > Host: localhost:8080
 > User-Agent: curl/7.43.0
 > Accept: */*
 > Cookie: XSRF-TOKEN=A_VALUE
 > X-XSRF-TOKEN:A_VALUE
 > Content-Type: application/json
 > Content-Length: 39
 >
 * upload completely sent off: 39 out of 39 bytes
 < HTTP/1.1 200
 < Cache-Control: no-cache, no-store, max-age=0, must-revalidate
 < Pragma: no-cache
 < Expires: 0
 < Set-Cookie: JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F; Path=/studio; HttpOnly
 < Content-Type: application/json;charset=UTF-8
 < Content-Language: en-US
 < Transfer-Encoding: chunked
 < Date: Mon, 22 Jan 2018 21:32:48 GMT
 <
 * Connection #0 to host localhost left intact
 {"username":"admin","first_name":"admin","last_name":"admin","email":"evaladmin@example.com"}

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 With Which the User Is Authorized to Work

http://docs.craftercms.org/en/3.0/developers/projects/studio/api/site/get-sites-per-user.html curl --cookie "XSRF-TOKEN=A_VALUE;JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F" -H "X-XSRF-TOKEN:A_VALUE"  -X GET http://localhost:8080/studio/api/1/services/api/1/site/get-per-user.json?username=admin
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:
{"sites":[{"id":9,"siteId":"ar","name":"ar","description":"","status":null,"liveUrl":null,"lastCommitId":"951004363449cc83209f307b1e9f110dab37fed7","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":null},{"id":5,"siteId":"diiot","name":"diiot","description":"","status":null,"liveUrl":null,"lastCommitId":"92d543eaa164b1ebfbdd6ce538ae028d4d6421b7","publishingEnabled":0,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":"92d543eaa164b1ebfbdd6ce538ae028d4d6421b7"},{"id":10,"siteId":"editorialcom","name":"editorialcom","description":"","status":null,"liveUrl":null,"lastCommitId":"503d922f226e8ab821073e23ef5a229f907212a0","publishingEnabled":1,"publishingStatusMessage":"","lastVerifiedGitlogCommitId":"503d922f226e8ab821073e23ef5a229f907212a0"},{"id":3,"siteId":"flow","name":"flow","description":"","status":null,"liveUrl":null,"lastCommitId":"21923775c3a1fc778a364d47884b9ee2bb4928a5","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":"21923775c3a1fc778a364d47884b9ee2bb4928a5"},{"id":8,"siteId":"vr","name":"vr","description":"","status":null,"liveUrl":null,"lastCommitId":"c67fd9dd25d1aa59ff13e3fda2a4387be50dfc69","publishingEnabled":1,"publishingStatusMessage":"idle|Idle","lastVerifiedGitlogCommitId":null}],"total":6}

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 Editorialcom Project

http://docs.craftercms.org/en/3.0/developers/projects/studio/api/content/write-content.html
curl -d "<page><content-type>/page/category-landing</content-type><display-template>/templates/web/pages/category-landing.ftl</display-template><merge-strategy>inherit-levels</merge-strategy><file-name>index.xml</file-name><folder-name>test3</folder-name><internal-name>test3</internal-name><disabled >false</disabled></page>" --cookie "XSRF-TOKEN=A_VALUE;JSESSIONID=2E114725C82F3EE44ADC04B578A3BE8F" -H "X-XSRF-TOKEN:A_VALUE"  -X POST "http://localhost:8080/studio/api/1/services/api/1/content/write-content.json?site=editorialcom&phase=onSave&path=/site/website/test3/index.xml&fileName=index.xml&user=admin&contentType=/page/category-landing&unlock=true"

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.

Conclusion

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.

Get out there and integrate!

Monitor application stability with Bugsnag to decide if your engineering team should be building new features on your roadmap or fixing bugs to stabilize your application.Try it free.

Topics:
web dev ,api ,cms

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}