Using CMI's RESTful Web Services

CMI features a RESTful interface that allows API interactions with the content on the site. Current supported formats include xml, json and hal+json. 

Current enabled resources include:

Content /node/{node}: GET, PATCH, DELETE methods: GET, POST
  /node: POST formats: hal_json, json, xml
    authentication: basic_auth
Content type /entity/node_type/{node_type}: GET methods: GET
    formats: hal_json, json, xml
    authentication: basic_auth
Field  /entity/field_config/{field_config}: GET methods: GET
    formats: hal_json, json, xml
    authentication: basic_auth
File /entity/file/{file}: GET, PATCH, DELETE methods: GET, POST
  /entity/file: POST formats: hal_json, json, xml
    authentication: basic_auth
Search page /entity/search_page/{search_page}: GET methods: GET
    formats: hal_json, json, xml
    authentication: basic_auth
Taxonomy term /taxonomy/term/{taxonomy_term}: GET, PATCH, DELETE methods: GET, POST
  /taxonomy/term: POST formats: hal_json, json, xml
    authentication: basic_auth
View /entity/view/{view}: GET methods: GET
    formats: hal_json, json, xml

Further resources and formats can be requested to be developed in a future release. Please see here for more details. 

Examples

It is important that currently, {node} refers to the node's Id as seen on the REST side bar of a product.

GET requests

With the above details in mind, for example if you wanted to get all fields and their content's in a json formatted output on the data product AGRI_2.51.0.0 which is found at the following link (http://cmi.ga.gov.au/agri2.51.0.0you would form a GET request that looks like this:

Curl
curl http://cmi.ga.gov.au/node/116?_format=json
Jquery
jQuery.ajax({
  url: 'http://cmi.ga.gov.au/node/116?_format=json',
  method: 'GET',
  success: function (comment) {
    console.log(comment);
  }
});

Further information on GET requests can be found here.

PATCH requests

If you wanted to modify the a field of a product; for example the title of DLCD_25_1.0.0 (http://52.64.197.68/dlcd251.0.0) to Dynamic Land Cover Dataset 25m 1.0.0 you would form a PATCH request that looks like this:

Curl
curl --include \
  --request PATCH \
  --user [YOUR USERNAME]:[YOUR PASSWORD] \
  --header 'Content-type: application/json' \
  --header 'X-CSRF-Token: [OBTAINED FROM http://cmi.ga.gov.au/rest/session/token]' \
  http://cmi.ga.gov.au/node/170?_format=json \
  --data-binary '{"title": [{"value":"Dynamic Land Cover Dataset 25m 1.0.0"}],"type":[{"target_id": "product","target_type": "node_type","target_uuid": "0ca00771-b5c4-47ce-9aef-0c32af21ab58"}]}'
Jquery
function getCsrfToken(callback) {
  jQuery
    .get(Drupal.url('rest/session/token'))
    .done(function (data) {
      var csrfToken = data;
      callback(csrfToken);
    });
}

function patchNode(csrfToken, node) {
  jQuery.ajax({
    url: 'http://cmi.ga.gov.au/node/170?_format=json',
    method: 'PATCH',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-Token': csrfToken
    },
    data: JSON.stringify(node),
    success: function (node) {
      console.log(node);
    }
  });
}

var newNode = {
  {"title": 
      [{"value":"Dynamic Land Cover Dataset 25m 1.0.0"}],
   "type":
      [{"target_id": "product",
      "target_type": "node_type",
      "target_uuid": "0ca00771-b5c4-47ce-9aef-0c32af21ab58"}]
  }'
}; 

getCsrfToken(function (csrfToken) {
  patchNode(csrfToken, newNode);
});

It is important to note that the field "type" is required when sending a PATCH request, otherwise an error will occur.

Further information on using the PATCH request can be found here.

POST requests

If you want to create a News article through the API such as an article with the title "Example news title" you would form a POST request that would look similar to this:

Curl
curl --include \
  --request POST \
  --user [YOUR USERNAME]:[YOUR PASSWORD] \
  --header 'Content-type: application/json' \
  --header 'X-CSRF-Token: [OBTAINED FROM http://cmi.ga.gov.au/rest/session/token]' \
  http://cmi.ga.gov.au/entity/node?_format=json \
  --data-binary '{"title":[{"value":"Example news title"}],"type":[{"target_id":"news_item"}]}'
JQuery
function getCsrfToken(callback) {
  jQuery
    .get(Drupal.url('rest/session/token'))
    .done(function (data) {
      var csrfToken = data;
      callback(csrfToken);
    });
}

function postNode(csrfToken, node) {
  jQuery.ajax({
    url: 'http://cmi.ga.gov.au/entity/node?_format=json',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-CSRF-Token': csrfToken
    },
    data: JSON.stringify(node),
    success: function (node) {
      console.log(node);
    }
  });
}

var newNode = {
  {
    "title": [{"value":"Example news title"}],
    "type":[{"target_id":"news_item"}]
  }
}; 

getCsrfToken(function (csrfToken) {
  postNode(csrfToken, newNode);
});

All required fields need to be included in the request with optional fields able to be added as needed. 

Further information on using the PATCH request can be found here.

Trouble Shooting

Code Description
400 'Bad Request' for invalid request
403 'Forbidden' when accessing protected resource/service with invalid credentials
404 'Not Found' when accessing non existing resource/service
405 'Method Not Allowed' when accessing existing resource/service with a HTTP method that is not allowed
500 'Internal Server Error' for technical errors (i.e. database connection error, etc.)

 

Further Reading

https://www.drupal.org/docs/8/core/modules/rest/1-getting-started-rest-configuration-rest-request-fundamentals