How to use RESTful web services

CMI features a RESTful interface that allows API interactions with the content on the site.

 

On this page

Current supported formats

Current enabled resources

Examples

Troubleshooting

Further reading

 


Current supported formats

Include XML, JSON and HAL+JSON

 


Current enabled resources

Include the following:

Content

/node/{node}: GET, PATCH, DELETE

/node: POST

methods: GET, 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

/entity/file: POST

methods: GET, 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

/taxonomy/term: POST

methods: GET, POST

formats: hal_json, json, xml

authentication: basic_auth

View /entity/view/{view}: GET

methods: GET

formats: hal_json, json, xml

 

Please contact us at cmi@ga.gov.au to request additional resources and formats to be developed in future releases.

 


Examples

Note that {node} currently refers to the product’s RESTful node ID (NID), which can be found under the Access tab.

GET requests

Take the product Australian Geographic Reference Image for example (NID: 116).

If you wish to get all fields and their content in a JSON-formatted output, create the following GET request:

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);
  }
});

For more information on GET requests, see GET for reading content entities.

PATCH requests

Take the product Dynamic Land Cover Dataset 25m 1.0.0 for example (NID: 170).

If you wish to modify the 'title' field of this product to become Dynamic Land Cover Dataset 25m 1.0.0 UPDATED, create the following PATCH request:

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.

For more information on PATCH requests, see PATCH for updating content entities.

POST requests

If you wish to create a news article titled CMI News through the API, create the following POST request:

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. Optional fields can be added as needed. 

For more information on POST requests, see POST for reading content entities.

 


Troubleshooting

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 (e.g. database connection error)

 


Further reading

See Getting started: REST request fundamentals