What’s Going on Here?
In part 1 and part 2 of this series, I talked about Drupal REST services, and authenticating, and querying data. Be sure to review those before continuing with this post.
This article talks about how to create or update data on Drupal using REST APIs. It will use the same authentication foundation as described in Part 2.
Update All the Things!
What kinds of things can you create or update or delete with the Drupal REST API?
- users
- forum topics
- articles
- taxonomy categories
- taxonomy terms
- comments
- and so on…
Pretty cool. Also, when creating entities, like users, all the normal drupal hooks will run. So that if you programmatically create a new user, and if you have a new-user hook that sends out an email…. then that hook will run and the email address for the newly-created user will get an email sent by Drupal. The API provides a nice way to provision a set of users all at one go, into Drupal, rather than asking each individual user to visit the site and self-register.
There are also special REST endpoints for doing things like resetting passwords or resending the welcome email.
So let’s look at some request payloads !
Modify an Existing Article
Request:
curl -i -X PUT \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H Accept:application/json \
-H content-type:application/json \
http://example.com/rest/node/4 \
-d '{
"title": "about multiple themes....",
"body": {
"und": [{
"value": "how to demonstrate multiple themes?. ...",
"summary": "multiple themes?",
"format": "filtered_html",
"safe_value": "themes",
"safe_summary": "themes..."
}]
}
}'
Create a Forum Topic
To create a new Forum post (Drupal calls it a Forum topic):
Request:
curl -i -X PUT \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H Accept:application/json \
-H content-type:application/json \
http://example.com/rest/node \
-d '{
"type": "forum",
"title": "test post?",
"language": "und",
"taxonomy_forums": { "und": "1" },
"body": {
"und": [{
"value" : "This is the full text of the forum post",
"summary": "this is a test1",
"format": "full_html"
}]
}
}'
This part…
"taxonomy_forums": { "und": "1" },
…tells which forum to post to. Actually the “parent forum” is a taxonomy term, not a forum container. Nodes carry a taxonomy term on them, to identify which forum they belong to.
If you specify an invalid forum id, you will get this json error response:
406 Unacceptable
...
{
"form_errors": {
"taxonomy_forums][und": "An illegal choice has been detected. Please contact the site administrator.",
"taxonomy_forums": "Select a forum."
}
}
Here’s another “create forum topic” request, to a different forum:
curl -i -X POST \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H Accept:application/json \
-H content-type:application/json \
http://example.com/rest/node \
-d '{
"type": "forum",
"title": "test post #2",
"language": "und",
"taxonomy_forums": { "und": "5" },
"body": {
"und": [{
"value" : "This is a test post. please ignore.",
"summary": "this is a test1",
"format": "full_html"
}]
}
}'
Notice the alternate forum id in that request, as compared to the prior one:
"taxonomy_forums": { "und": "5" }
Determine the available forums and ID numbers
Step 1: query the vocabulary that corresponds to “forums”:
curl -i -X GET \ -H accept:application/json \ -H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \ 'http://example.com/rest/taxonomy_vocabulary?parameters\[machine_name\]=forums'
Example Response:
[{
"vid": "1",
"name": "Forums",
"machine_name": "forums",
"description": "Forum navigation vocabulary",
"hierarchy": "0",
"module": "forum",
"weight": "-10",
"uri": "http://myserver/rest/taxonomy_vocabulary/1"
}]
The important part is the “vid” – which is the vocabulary ID.
Step 2: Query the terms for that vocabulary. This gives all forum names and IDs.
curl -i -X GET \ -H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \ -H Accept:application/json \ -H content-type:application/json \ 'http://example.com/rest/taxonomy_term?parameters\[vid\]=1'
Example response:
Response:
[{
"tid": "8",
"vid": "1",
"name": "Getting Started",
"description": "",
"format": null,
"weight": "0",
"uuid": "7ff7ce10-0082-46f6-9edd-882410b7c304",
"depth": 0,
"parents": ["0"]
}, {
"tid": "1",
"vid": "1",
"name": "General discussion",
"description": "",
"format": null,
"weight": "1",
"uuid": "dbf914e7-42c2-45f6-b77a-e66a0da72310",
"depth": 0,
"parents": ["0"]
}, {
"tid": "4",
"vid": "1",
"name": "Security and Privacy Issues",
"description": "",
"format": null,
"weight": "2",
"uuid": "7496bfd7-2cb8-4f87-a1e4-f45b1956a01e",
"depth": 0,
"parents": ["0"]
}]
The tid in each array element is what you must use in the “taxonomy_forums”: { “und”: “4” }, … when POSTing a new forum node.
Delete a node
Deleting a node means removing an article, a forum topic (post), a comment, etc.
The request:
curl -i -X DELETE \ -H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \ -H X-CSRF-Token:w98sdb9udjiskdjs \ -H Accept:application/json \ http://example.com/rest/node/8
Example response:
[true]
Weird response, but ok.
By the way, if the cookie and token has timed out, for any of these create, update, or delete calls you may see this response:
["Access denied for user anonymous"].
There is no explicit notice that the cookie has timed out. The remedy is
to re-authenticate and submit the request again.
Delete a taxonomy term
Deleting a taxonomy term in the taxonomy vocabulary for forums would imply deleting a forum.
curl -i -X DELETE \ -H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \ -H X-CSRF-Token:w98sdb9udjiskdjs \ -H Accept:application/json \ http://dev-wagov1.devportal.apigee.com/rest/taxonomy_term/7
Create a taxonomy term
Creating a taxonomy term in the taxonomy vocabulary for forums would imply creating a forum.
curl -i -X POST \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H Accept:application/json \
-H content-type:application/json \
http://dev-wagov1.devportal.apigee.com/rest/taxonomy_term \
-d '{
"vid": "1",
"name": "Another Forum on the site",
"description": "",
"format": null,
"weight": "10"
}'
The UUID and TID for the forum will be generated for you. Unfortunately, the tid will not be returned for you to reference. You need to query to find it. Use the name of the forum you just created:
Request:
curl -i -X GET \ -H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \ -H Accept:application/json \ 'http://example.com/rest/taxonomy_term?parameters\[name\]=Another+Forum+on+the+site'
Example Response:
[{
"tid": "36",
"vid": "1",
"name": "Another Forum on the site",
"description": "",
"format": null,
"weight": "10",
"uuid": "dcbe0118-c160-4556-b0b6-1813241bb851",
"uri": "http://example.com/rest/taxonomy_term/36"
}]
Make sure you use unique names for these taxonomy terms.
Create a new user
curl -i -X POST \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H accept:application/json \
-H content-type:application/json \
http://example.com/rest/user -d '{
"name" : "TestUser1",
"mail" : "Dchiesa+Testuser1@apigee.com",
"pass": "secret123",
"timezone": "America/Los_Angeles",
"field_first_name": {
"und": [{ "value": "Dino"}]
},
"field_last_name": {
"und": [{ "value": "Chiesa"}]
}
}'
Response:
{"uid":"7","uri":"http://example.com/rest/user/7"}
Resend the welcome email
curl -i -X POST \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H accept:application/json \
-H content-type:application/json \
http://example.com/rest/user/7/resend_welcome_email -d '{}'
Reset a user password
curl -i -X POST \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H accept:application/json \
-H content-type:application/json \
http://example.com/rest/user/7/password_reset -d '{}'
Update a user
This shows how to set the user status to 0, in order to de-activate the user.
curl -i -X PUT \
-H Cookie:SESS02caabc123=ShBy6ue5TTabcdefg \
-H X-CSRF-Token:w98sdb9udjiskdjs \
-H accept:application/json \
-H content-type:application/json \
http://example.com/rest/user/6 -d '{
"status" : "0"
}'
You could of course update any of the other user attributes as well.
That ought to get you started with creating and updating things in Drupal via the REST Server.
Remember, the basic rules are:
- pass the cookie for each REST query call
- Pass the cookie and X-CSRF-Token when doing create, update or
delete - have fun out there!
Good luck. Contact me here if these examples are unclear.