Gobble plugin for Craft 3
A simple plugin for making REST API requests directly from your templates., (*1)
Requirements
This plugin requires Craft 3., (*2)
Installation
To install the plugin:, (*3)
-
open your terminal and go to your Craft project:, (*4)
cd /path/to/project
, (*5)
-
tell Composer to load the plugin:, (*6)
composer require jfd/gobble
-
In the Control Panel, go to Settings → Plugins and click the "Install" button for Gobble., (*7)
Using Gobble
A simple example:, (*8)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'GET'
}) %}
{% for item in response.body %}
- {{ item.title }}
{% endfor %}
Required parameters
url
The complete URL to which the request should be sent, including the base URL and the endpoint., (*9)
method
The HTTP method to use for the request. Can be GET
, POST
, PUT
, PATCH
or DELETE
., (*10)
Optional parameters
auth
Use the auth
parameter to pass an array of HTTP authentication parameters along with the request. The array must contain the username in index [0], the password in index [1], and you can optionally provide a built-in authentication type in index [2]., (*11)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'GET',
'auth': [
'username',
'password',
'digest' // optional
]
}) %}
body
Use the body
parameter to pass body content along with an entity enclosing request (e.g. PUT, POST, PATCH)., (*12)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'POST',
'body': 'Some body content...'
}) %}
Use the headers
parameter to pass an associative array of headers along with the request. Each key is the
name of a header, and each value is a string or array of strings representing the header field values., (*13)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'GET',
'headers': {
'key': 'xxxxxxxxxxxxxxxxx',
'secret': 'xxxxxxxxxxxxxxxxx'
}
}) %}
json
Use the json
parameter to easily pass along JSON-encoded data as the body of the request. A Content-Type header of application/json
will be added if no Content-Type header is already present in the request., (*14)
Note: The json
parameter cannot be used with the body
parameter. If the json
parameter has been defined, the body
parameter will be ignored., (*15)
Also: if the json
parameter has been set, a Content-Type
header will be applied with a value of application/json
. Any Content-Type
header set in the template will be ignored., (*16)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'GET',
'json': {
'key1': 'value1',
'key2': 'value2'
}
}) %}
query
Use the query
parameter to pass an associative array of query string values or a query string along with the request., (*17)
Note: Query strings specified in the query
parameter will overwrite all query string values supplied in the URL of a request., (*18)
Pass an array:, (*19)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'POST',
'query': {
'key1': 'value1',
'key2': 'value2'
}
}) %}
Pass a string:, (*20)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'POST',
'query': 'key1=value1&key2=value2'
}) %}
Response
The response will be in the form of an array containing four items:, (*21)
statusCode
The HTTP status code:, (*22)
{{ response.statusCode }} // e.g. 200
reasonPhrase
The corresponding reason phrase:, (*23)
{{ response.reasonPhrase }} // e.g. OK
The response headers., (*24)
Output all:, (*25)
{{ dump(response.headers) }}
/*
array (size=5)
'Date' => string 'Wed, 17 Jan 2018 17:11:41 GMT' (length=29)
'Server' => string 'Microsoft-IIS/8.5' (length=17)
'ContentLength' => string '2668' (length=4)
'ContentType' => string 'application/json; charset=utf-8' (length=31)
'XPoweredBy' => string 'ASP.NET' (length=7)
*/
Output a single header:, (*26)
{{ response.headers.ContentType }} // application/json; charset=utf-8
body
The body of the response, (*27)
Example:, (*28)
{% set response = gobble({
'url': 'https://example.com/api/endpoint',
'method': 'GET'
}) %}
{{ response.statusCode }} // 200
{{ response.reasonPhrase }} // OK
{% for item in response.body %}
- {{ item.title }}
{% endfor %}