Drupal 8 REST API ServicesJoseph Chin1 / 36

Hello

Joseph Chin
Drupal Solution Architect since 2007
Singapore Drupal Meetup committee member
jchin1968 on
Follow along here: https://rawgit.com/jchin1968/d8-rest-api-presentation/master/index.html

2 / 36

TopicsREST Basics
Setting up REST Services
Making API calls
Authentication
Using Views to ceate a custom endpoint
Q & A
3 / 36

assumes you understand what is REST and why you'd want to use it.

REST Basics

Action
Method
URL Path
Data


Create
POST
endpoint
Yes

Read
GET
endpoint/{id}
No

Update
PATCH
endpoint/{id}
Yes

Delete
DELETE
endpoint/{id}
No

4 / 36

Action	Method	URL Path	Data
Create	POST	endpoint	Yes
Read	GET	endpoint/{id}	No
Update	PATCH	endpoint/{id}	Yes
Delete	DELETE	endpoint/{id}	No

PUT is for replacing the entire content and requires all the fields where as PATCH only require the changed data

Setup5 / 36

Setup - Modules

Required
Should Be
Optional

Serialization
REST UI
HAL

RESTFul Web Services
Views
HTTP Basic Authentication

JSON API

Graph QL

6 / 36

Required	Should Be	Optional
Serialization	REST UI	HAL
RESTFul Web Services	Views	HTTP Basic Authentication
		JSON API
		Graph QL

HAL - stands for Hypertext Application Language
provides hyperlinks to related content? Not really sure of it's value
HTTP Basic Auth. - better to use session cookies as more secure. Don't have to resend credentials everytime. user id/password can be intercepted in logs if credentials are passed via URL
JSON API - Include lists. Allows for simple filtering, pager, sorting via API
Graph QL - standard created by Facebook to allow for complex querying. Kinda like SQL for REST

Setup - REST Resources

Configuration / Web services / REST

7 / 36

this screen is made available by REST UI module
Enable Content and User
Many resources available such as Action, Block, User Role, Taxonomy terms and vocabularies
Note the path available for each REST resource

Setup - REST Resources

8 / 36

For each resource, enable required Request types: GET, POST, PATCH, DELETE. Enable JSON and cooke authentication

Setup - User PermissionsREST APIs follow the same permission as normal pages
9 / 36

Article node publicly accessible for viewing
User node is accessible only by administrator

Setup - CORS

CORS - Cross Origin Resource Sharing
In service.yml

    cors.config:
        enabled: true 
        allowedHeaders: ['*']
        allowedMethods: ['GET', 'POST', 'PATCH']
        allowedOrigins: ['http://trusted-nodejs-site:3000']
        exposedHeaders: true 
        maxAge: 1000 
        supportsCredentials: true

10 / 36

CORS - cross origin resource sharing
security feature to prevent a script from one domain to access resources (i.e. image, js, css, json) from another
Drupal 8 is configured by default to prevent resource sharing

Making REST
API Calls11 / 36

Basic GET Request

Method: GET
URL: http://rest-demo/node/1?_format=json

12 / 36

Basic GET Response

{
  "nid": [{ "value" : 1 }], 
    .
    .
  "status": [{ "value" : true }],
  "title": [{ "value" : "The Quick Brown Fox" }],
    .
    .
  "body": [{
    "value" : "<p>The quick brown fox....the lazy dogs.</p>\r\n",
    "format" : "basic_html",
    "summary" : ""
  }],
    .
    .
}

13 / 36

Simplest request. Go to a browser and simply enter a URL
In Drupal 8, you require the query parameter _format=json to identify it is json

Basic GET Sample Code

    jQuery.ajax({
      method: "GET",
      url: "http://rest-demo/node/1?_format=json",
    })
      .done(function(data, textStatus, jqXHR) {
        $('h1#title').html(data.title[0]['value']);
      })
      .fail(function(jqXHR, textStatus) {
        ...
      })

14 / 36

.success and .error callbacks are deprecated as of jQuery 3.0 and relaced by Promise methods .done and .fail

Method: POST
URL: http://rest-demo/user/login?_format=json
Data:

      { 
        "name" : "joe", 
        "pass" : "test" 
      }

withCredentials: true

15 / 36

{
  "current_user" : { 
    "uid" : "2", 
    "name" : "joe", 
    "roles" : [ "authenticated", "editor", "member" ]
  },
  "csrf_token":"vVlThBvK_K0PNmkcSeNr1ntw8qxADc8v5h17Hugsiok",
  "logout_token":"zLskC3cKPp1rV00E7jxXihNk1Zk-uaAldsQiHa_VaSM"
}

Retain CSRF Token for "unsafe" requests i.e. POST, PATCH, DELETE
If non-browser request (i.e. PHP code), retain the session cookie from the response header

16 / 36

Slightly more complicated as it expects an HTTP body which you can't provide through the URL
Use something like Postman to construct the body
Sends out an OPTIONS (pre-flight) request first to see if you are allowed to connect and then the second request is the actual POST with your login credentials
When on a browser (i.e. using Javascript), the browser handles the session cookie.
When on a server, i.e. PHP cURL commands, you will need to construct a HTTP header with the session cookie.
The CSRF token is required for "Unsafe" requests ie. POST, PATCH, DELETE. Safe requests such as GET do not require the token

    jQuery.ajax({
      method: "POST",
      url: "http://rest-demo/user/login?_format=json",
      data: JSON.stringify({ name: "joe", pass: "test" }),
      xhrFields: { withCredentials: true },
    })
      .done(function(data, textStatus, jqXHR) {
        csrfToken = data.csrf_token;
        ...
      })
      .fail(function(jqXHR, textStatus, errorThrown) {
        ...
      })

17 / 36

Authenticated GET Request

Method: GET
URL: http://rest-demo/user/2?_format=json
For browsers, set withCredentials = true
For non-browsers, set session cookie in the request header

18 / 36

Session cookies are automatically handled with browser requests BUT will need to be set in the HTTP header for server-side requests

Authenticated GET Response

{
  "uid" : [{ "value" : 2 }], 
    .
    .
  "name" : [{ "value" : "joe" }],
  "mail" : [{ "value" : "joe@test.com" }],
  "timezone" : [{ "value" : "Asia/Singapore" }],
  "status" : [{ "value" : true }],
    .
    .
}

19 / 36

Authenticated GET Code

    jQuery.ajax({
      method: "GET",
      url: "http://rest-demo/user/2?_format=json",
      xhrFields: { withCredentials: true },
    })
      .done(function(data, textStatus, jqXHR ) {
        $('h1#username').html(data.name[0]['value']);
      })
      .fail(function( jqXHR, textStatus ) {
        ...
      })

20 / 36

Create Node Request

Method: POST
Header:
- Content-Type: application/json
- X-CSRF-Token: vVlThBvK_K0P......v5h17Hugsiok
URL: http://rest-demo/node?_format=json
Data:

      {
        "type" :[{ "target_id" : "article" }],
        "title" :[{ "value" : "Hello World" }],
        "body" : [{ "value" : "How are you?" }]
      }

21 / 36

Create Node Response

{
  "nid": [{ "value" : 2 }], 
    .
    .
  "type": [{ "target_id" : "article", .... }],
  "status": [{ "value" : true }],
  "title": [{ "value" : "Hello World" }],
    .
    .
}

22 / 36

Create Node Sample Code

    jQuery.ajax({
      method: "POST",
      url: "http://rest-demo/node?_format=json",
      data: JSON.stringify({
        "type" :[{ "target_id" : "article" }],
        "title" :[{ "value" : "Hello World" }],
        "body" : [{ "value" : "How are you?" }]
      }),
      xhrFields: { withCredentials: true },
      headers: { 
        "X-CSRF-Token": csrfToken,
        "Content-Type": "application/json"
      }
    })
      .done(function(data, textStatus, jqXHR ) {
        ...
      })
      .fail(function( jqXHR, textStatus ) {
        ...
      })

23 / 36

Update Node Request

Method: PATCH
Header:
- Content-Type: application/json
- X-CSRF-Token: vVlThBvK_K0P......v5h17Hugsiok
URL: http://rest-demo/node/2?_format=json
Data:

      {
        "type" : [{ "target_id" : "article" }],
        "title" : [{ "value" : "Hello Cebu" }]
      }

24 / 36

Update Node Response

{
  "nid" : [{ "value" : 2 }], 
    .
    .
  "title" : [{ "value" : "Hello Cebu" }],
    .
    .
}

25 / 36

Update Node Sample Code

    jQuery.ajax({
      method: "PATCH",
      url: "http://rest-demo/node/" + nid + "?_format=json",
      data: JSON.stringify({
        "type" :[{ "target_id" : "article" }],
        "title" :[{ "value" : "Hello Cebu" }],
      }),
      xhrFields: { withCredentials: true },
      headers: { 
        "X-CSRF-Token": csrfToken,
        "Content-Type": "application/json"
      }
    })
      .done(function(data, textStatus, jqXHR ) {
        ...
      })
      .fail(function( jqXHR, textStatus ) {
        ...
      })

26 / 36

Delete Node Request

Method: DELETE
Header:
- X-CSRF-Token: vVlThBvK_K0P......v5h17Hugsiok
URL: http://rest-demo/node/2?_format=json

27 / 36

Delete Node ResponseHTTP 204 - No Content
28 / 36

HTTP 204 - Not an error message

Delete Node Sample Code

    jQuery.ajax({
      method: "DELETE",
      url: "http://rest-demo/node/" + nid + "?_format=json",
      xhrFields: { withCredentials: true },
      headers: { 
        "X-CSRF-Token": csrfToken,
        "Content-Type": "application/json"
      }
    })
      .done(function(data, textStatus, jqXHR ) {
        ...
      })
      .fail(function( jqXHR, textStatus ) {
        ...
      })

29 / 36

Logout Request

Method: GET
URL: http://rest-demo/user/logout
Note: _format=json query parameter not required

30 / 36

Logout ResponseHTTP 302 (Redirect) to the home page
response data will be HTML tags 
31 / 36

Logout Sample Code

    jQuery.ajax({
      method: "GET",
      url: "http://rest-demo/user/logout",
      xhrFields: { withCredentials: true },
    })
      .done(function(data, textStatus, jqXHR ) {
        ...
      })
      .fail(function( jqXHR, textStatus ) {
        ...
      })

32 / 36

Custom Endpoints33 / 36

Create JSON ListNo lists provided by default
Create using Views as a "REST export"
34 / 36

Accessing a single entity via REST is provided out of the box but to get a list requires creating views

References

35 / 36

Q & A36 / 36

↑, ←, Pg Up, k	Go to previous slide
↓, →, Pg Dn, Space, j	Go to next slide
Home	Go to first slide
End	Go to last slide
Number + Return	Go to specific slide
b / m / f	Toggle blackout / mirrored / fullscreen mode
c	Clone slideshow
p	Toggle presenter mode
t	Restart the presentation timer
?, h	Toggle this help

Drupal 8 REST API Services

Joseph Chin

Hello

Topics

REST Basics

Setup

Setup - Modules

Setup - REST Resources

Configuration / Web services / REST

Setup - REST Resources

Setup - User Permissions

Setup - CORS

Making RESTAPI Calls

Basic GET Request

Basic GET Response

Basic GET Sample Code

Login Request

Login Response

Login Sample Code

Authenticated GET Request

Authenticated GET Response

Authenticated GET Code

Create Node Request

Create Node Response

Create Node Sample Code

Update Node Request

Update Node Response

Update Node Sample Code

Delete Node Request

Delete Node Response

Delete Node Sample Code

Logout Request

Logout Response

Logout Sample Code

Custom Endpoints

Create JSON List

References

Q & A

Hello

Help

Making REST
API Calls