SlideShare a Scribd company logo
1 of 86
Stop the noise!
Introduction to the JSON:API specification
Björn Brala – Technical Director @swis.nl
Before we start
-Feel free to ask questions!
-https://swis.nl/drupaljam
-This presentation
-All mentioned links (and more)
Clients
Employees (Back office)
CRM ERP FIN
Clients
Employees (Back office)
CRM ERP FIN
Clients
Employees (Back office)
An optimal digital experience. Always and everywhere.
CRM ERP FIN
Clients
Employees (Back office)
An optimal digital experience. Always and everywhere.
CRM ERP FIN
Clients
Employees (Back office)
An optimal digital experience. Always and everywhere.
Stop the noise!
If you’ve ever argued with your team about the way your JSON
responses should be formatted, JSON:API can be your anti-
bikeshedding tool.
Bikeshedding
Any colour will do, really…
What is JSON:API
XML!
JSON
No nesting
MyREST
oData
What is JSON:API
What is JSON:API
History of {JSON:API}
History of {JSON:API}
History of {JSON:API}
- Embed.js creator
- Rust Core Team
- Retired Ruby on Rails and jQuery core teams.
- ECMAScript's TC39 standards committee member
- W3C's TAG (Technical Architecture Group) memberYehuda Katz
Eliminate the need for ad-hoc code per
application to communicate with servers
that communicate in a well-defined way.
Is the specification used?
Is it used?
150+ client and server implementations
available in about 20 different languages
Is it used?
Drupal jsonapi module
Drupal jsonapi module
• 2016 Started by Mateu Aguiló Bosch (e0ipso – eh-oh-ipso)
• 2017 Release 1.0
• 2017 Aquia provided Wim Leers and Gabe Sollice
• 2019 januari Release 2.0
• 2019 march Committed to core!
• 28 months, 450 commits, 32 releases and 5,500 test runs.
Core concepts of JSON:API
Core concepts of JSON:API
-Uses basic HTTP
- GET, POST, PATCH, DELETE
-Response in JSON
- Content type: application/vnd.api+json
Basic HTTP request - Core concepts of JSON:API
GET /articles HTTP/1.1
Accept: application/vnd.api+json
JSON:API document - Core concepts of JSON:API
{
data: {
type: "node--article",
id: "d71db11d-ceef-401f-b340-f0ac1a877dfd",
attributes: {
title: “Stop the noise!“
},
relationships: {
uid: {
data: {
type: "user--user",
id: "c47322d3-2131-474b-a724-444acf33648b",
},
links: {
self: "https://example.com/jsonapi/node/article/d71../relationships/uid",
related: "https://example.com/jsonapi/node/article/d71../uid"
}
}
},
links: {
self: "https://example.com/jsonapi/node/article/d71..."
}
},
// ...
Compound documents
Compound documents
To reduce the number of HTTP requests,
servers MAY allow responses that include
related resources along with the requested
primary resources. Such responses are
called “compound documents”.
Example - Compound documents
{
"data": [
{
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"links": {...},
"relationships": {
“comments": {
"links": {...},
"data": {
"type": “comments",
"id": “5"
}
}
}
}
],
"included": [...]
}
Example - Compound documents
{
"data": [...],
"included": [
{
"type": “comments",
"id": “5",
"attributes": {
“body": “first!"
},
"relationships": {
“author": {
"data": {
"type": “people",
"id": “2"
}
}
}
"links": {
"self": "http://example.com/comments/9"
}
}
]
}
Inclusion of related resources
Inclusion of related resources
GET /articles/1?include=author HTTP/1.1
Accept: application/vnd.api+json
Inclusion of related resources
GET /articles/1?include=author,comments HTTP/1.1
Accept: application/vnd.api+json
Inclusion of related resources
GET /articles/1?include=author,comments.author HTTP/1.1
Accept: application/vnd.api+json
Sparse fieldsets
Sparse fieldsets
GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json
Filtering
Filtering
The filter query parameter is reserved for
filtering data. Servers and clients SHOULD
use this key for filtering operations.
Filtering in Drupal
Filtering in Drupal
GET /articles?filter[field_name]=value&filter[field_other]=value HTTP/1.1
Accept: application/vnd.api+json
Short and normal - Filtering in Drupal
SHORT:
?filter[field_first_name]=Janis
NORMAL:
?filter[a-label][condition][path]=field_first_name
&filter[a-label][condition][operator]=%3D (an encoded ‘=‘)
&filter[a-label][condition][value]=Janis
Features - Filtering in Drupal
-Supported operators
-Condition grouping
-Paths
- Filtering in Drupal
?filter[first_name_filter][condition][path]=field_first_name
&filter[first_name_filter][condition][operator]=%3D
&filter[first_name_filter][condition][value]=Janis
DrupaljsonapiQueryEntityCondition::$allowedOperators = [
'=', '<>', // Equals
'>', '>=', '<', '<=', // Greater or less than
'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison
'IN', 'NOT IN', // Value in set
'BETWEEN', 'NOT BETWEEN', // Range comparison
'IS NULL', 'IS NOT NULL', // NULL comparison
];
Supported operators
Supported operators - Filtering in Drupal
?filter[first_name_filter][condition][path]=field_first_name
&filter[first_name_filter][condition][operator]=STARTS_WITH
&filter[first_name_filter][condition][value]=J
DrupaljsonapiQueryEntityCondition::$allowedOperators = [
'=', '<>', // Equals
'>', '>=', '<', '<=', // Greater or less than
'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison
'IN', 'NOT IN', // Value in set
'BETWEEN', 'NOT BETWEEN', // Range comparison
'IS NULL', 'IS NOT NULL', // NULL comparison
];
Supported operators - Filtering in Drupal
?filter[first_name_filter][condition][path]=field_first_name
&filter[first_name_filter][condition][operator]=IN
&filter[first_name_filter][condition][value][]=Janice
&filter[first_name_filter][condition][value][]=John
&filter[first_name_filter][condition][value][]=Jeff
DrupaljsonapiQueryEntityCondition::$allowedOperators = [
'=', '<>', // Equals
'>', '>=', '<', '<=', // Greater or less than
'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison
'IN', 'NOT IN', // Value in set
'BETWEEN', 'NOT BETWEEN', // Range comparison
'IS NULL', 'IS NOT NULL', // NULL comparison
];
Features - Filtering in Drupal
-Supported operators
-Condition grouping
-Paths
Condition grouping - Filtering in Drupal
Show me the users that have the job developer
and have the first or last name ‘smith’.
Condition grouping - Filtering in Drupal
?filter[or_group][group][conjunction]=OR
&filter[first_name_filter][condition][path]=field_first_name
&filter[first_name_filter][condition][value]=smith
&filter[first_name_filter][condition][memberOf]=or_group
&filter[last_name_filter][condition][path]=field_last_name
&filter[last_name_filter][condition][value]=smith
&filter[last_name_filter][condition][memberOf]=or_group
&filter[job_filter][condition][path]=job
&filter[job_filter][condition][value]=developer
Features - Filtering in Drupal
-Supported operators
-Condition grouping
-Paths
Condition grouping - Filtering in Drupal
?filter[career][condition][path]=field_career.name
&filter[career][condition][operator]=%3D
&filter[career][condition][value]=Rockstar
Examples
SHORT
filter[status][value]=1
NORMAL
filter[status-filter][condition][path]=status
filter[status-filter][condition][value]=1
Only get published nodes
- Filtering in DrupalExamples
Examples - Filtering in Drupal
SHORT
filter[uid.name][value]=admin
NORMAL
filter[name-filter][condition][path]=uid.name
filter[name-filter][condition][value]=admin
Get nodes created by user admin
Examples - Filtering in Drupal
SHORT
filter[title][operator]=CONTAINS&filter[title][value]=Foo
NORMAL
filter[title-filter][condition][path]=title
filter[title-filter][condition][operator]=CONTAINS
filter[title-filter][condition][value]=Foo
Filter nodes where ‘title’ contains ‘Foo’
Examples - Filtering in Drupal
FILTER BY LOCALITY
filter[field_address][condition][path]=field_address.locality
filter[field_address][condition][value]=Mordor
FILTER BY ADDRESS LINE
filter[field_address][condition][path]=field_address.address_line1
filter[field_address][condition][value]=Rings Street
Filter by non-standard complex field
Sorting
Sorting
?sort=created
?sort=-created
?sort=author,-created
?sort=uid.name,-created
The Drupal way - Sorting
SHORT:
?sort=uid.name,-created
NORMAL:
?sort[sort-created][path]=created
&sort[sort-created][direction]=DESC
&sort[sort-author][path]=uid.name
Pagination
Filtering
A server MAY provide links to traverse a
paginated data set (“pagination links”).
The page query parameter is reserved for
pagination. Servers and clients SHOULD use
this key for pagination operations.
Pagination in Drupal
Pagination in Drupal
{
"data": [
{"type": "sample--type", "id": "abcd-uuid-here"},
{"type": "sample--type", "id": "efgh-uuid-here"},
{"type": "sample--type", "id": "ijkl-uuid-here"}
],
"links": {
"self": "<collection_url>?page[offset]=1&page[limit]=3",
"next": "<collection_url>?page[offset]=2&page[limit]=3",
"prev": "<collection_url>?page[offset]=0&page[limit]=3"
}
}
Limits - Pagination
-Maximum page limit of 50
-No pagecount available
Creating, updating and deleting resources
Creating resources
{
"data": {
"type": "photos",
"attributes": {
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
},
"relationships": {
"photographer": {
"data": {
"type": "people",
"id": "9"
}
}
}
}
}
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Creating resources
{
"data": {
"type": "photos",
"id": "550e8400-e29b-41d4-a716-446655440000",
"attributes": {
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
},
"relationships": {
"photographer": {
"data": {
"type": "people",
"id": "9"
}
}
}
}
}
HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json
Updating resources
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "To TDD or Not"
}
}
}
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Updating resource relations
{
"data": {
"type": "articles",
// ...
"relationships": {
"author": {
"data": { "type": "people", "id": "1" }
},
"tags": {
"data": [
{ "type": "tags", "id": "2" },
{ "type": "tags", "id": "3" }
]
},
"comments": {
"data": []
}
}
}
}
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Deleting resources
DELETE /articles/1 HTTP/1.1
Accept: application/vnd.api+json
What did we learn today?
What did we learn today?
-Documents structure
-Limit data in responses
-Manipulate data
Thank you
Questions?
• Presentation, these links and more
• https://swis.nl/drupaljam
• Leave your email theres
• Slack
• #jsonapi and #contenta
• JSON:API specification
• https://jsonapi.org
• Drupal’s great JSON:API documentation
• https://www.drupal.org/docs/8/modules/jsonapi
• API first initiative
• https://www.drupal.org/about/strategic-initiatives/api-first
Questions?
What’s your flavor?
What’s your flavor?
swis.nl/drupaljam

More Related Content

What's hot

Python을 활용한 챗봇 서비스 개발 2일차
Python을 활용한 챗봇 서비스 개발 2일차Python을 활용한 챗봇 서비스 개발 2일차
Python을 활용한 챗봇 서비스 개발 2일차Taekyung Han
 
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기[2018 데이터야놀자] 웹크롤링 좀 더 잘하기
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기wangwon Lee
 
What is REST API? REST API Concepts and Examples | Edureka
What is REST API? REST API Concepts and Examples | EdurekaWhat is REST API? REST API Concepts and Examples | Edureka
What is REST API? REST API Concepts and Examples | EdurekaEdureka!
 
devops 2년차 이직 성공기.pptx
devops 2년차 이직 성공기.pptxdevops 2년차 이직 성공기.pptx
devops 2년차 이직 성공기.pptxByungho Lee
 
검색엔진이 데이터를 다루는 법 김종민
검색엔진이 데이터를 다루는 법 김종민검색엔진이 데이터를 다루는 법 김종민
검색엔진이 데이터를 다루는 법 김종민종민 김
 
데이터가 흐르는 조직 만들기 - 마이리얼트립
데이터가 흐르는 조직 만들기 - 마이리얼트립데이터가 흐르는 조직 만들기 - 마이리얼트립
데이터가 흐르는 조직 만들기 - 마이리얼트립승화 양
 
Little Big Data #1. 바닥부터 시작하는 데이터 인프라
Little Big Data #1. 바닥부터 시작하는 데이터 인프라Little Big Data #1. 바닥부터 시작하는 데이터 인프라
Little Big Data #1. 바닥부터 시작하는 데이터 인프라Seongyun Byeon
 
webservice scaling for newbie
webservice scaling for newbiewebservice scaling for newbie
webservice scaling for newbieDaeMyung Kang
 
Understanding REST APIs in 5 Simple Steps
Understanding REST APIs in 5 Simple StepsUnderstanding REST APIs in 5 Simple Steps
Understanding REST APIs in 5 Simple StepsTessa Mero
 
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개if kakao
 
파이썬을 활용한 웹 크롤링
파이썬을 활용한 웹 크롤링파이썬을 활용한 웹 크롤링
파이썬을 활용한 웹 크롤링HWANGTAEYONG
 
Aem sling resolution
Aem sling resolutionAem sling resolution
Aem sling resolutionGaurav Tiwari
 
Massive service basic
Massive service basicMassive service basic
Massive service basicDaeMyung Kang
 
서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)수보 김
 
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)Jaikwang Lee
 
elasticsearch_적용 및 활용_정리
elasticsearch_적용 및 활용_정리elasticsearch_적용 및 활용_정리
elasticsearch_적용 및 활용_정리Junyi Song
 
REST-API design patterns
REST-API design patternsREST-API design patterns
REST-API design patternsPatrick Savalle
 

What's hot (20)

Python을 활용한 챗봇 서비스 개발 2일차
Python을 활용한 챗봇 서비스 개발 2일차Python을 활용한 챗봇 서비스 개발 2일차
Python을 활용한 챗봇 서비스 개발 2일차
 
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기[2018 데이터야놀자] 웹크롤링 좀 더 잘하기
[2018 데이터야놀자] 웹크롤링 좀 더 잘하기
 
Web Scrapping Using Python
Web Scrapping Using PythonWeb Scrapping Using Python
Web Scrapping Using Python
 
What is REST API? REST API Concepts and Examples | Edureka
What is REST API? REST API Concepts and Examples | EdurekaWhat is REST API? REST API Concepts and Examples | Edureka
What is REST API? REST API Concepts and Examples | Edureka
 
devops 2년차 이직 성공기.pptx
devops 2년차 이직 성공기.pptxdevops 2년차 이직 성공기.pptx
devops 2년차 이직 성공기.pptx
 
검색엔진이 데이터를 다루는 법 김종민
검색엔진이 데이터를 다루는 법 김종민검색엔진이 데이터를 다루는 법 김종민
검색엔진이 데이터를 다루는 법 김종민
 
데이터가 흐르는 조직 만들기 - 마이리얼트립
데이터가 흐르는 조직 만들기 - 마이리얼트립데이터가 흐르는 조직 만들기 - 마이리얼트립
데이터가 흐르는 조직 만들기 - 마이리얼트립
 
Little Big Data #1. 바닥부터 시작하는 데이터 인프라
Little Big Data #1. 바닥부터 시작하는 데이터 인프라Little Big Data #1. 바닥부터 시작하는 데이터 인프라
Little Big Data #1. 바닥부터 시작하는 데이터 인프라
 
webservice scaling for newbie
webservice scaling for newbiewebservice scaling for newbie
webservice scaling for newbie
 
Understanding REST APIs in 5 Simple Steps
Understanding REST APIs in 5 Simple StepsUnderstanding REST APIs in 5 Simple Steps
Understanding REST APIs in 5 Simple Steps
 
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개
카카오 광고 플랫폼 MSA 적용 사례 및 API Gateway와 인증 구현에 대한 소개
 
파이썬을 활용한 웹 크롤링
파이썬을 활용한 웹 크롤링파이썬을 활용한 웹 크롤링
파이썬을 활용한 웹 크롤링
 
Aem sling resolution
Aem sling resolutionAem sling resolution
Aem sling resolution
 
Massive service basic
Massive service basicMassive service basic
Massive service basic
 
서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)서버학개론(백엔드 서버 개발자를 위한)
서버학개론(백엔드 서버 개발자를 위한)
 
API 101 event.pdf
API 101 event.pdfAPI 101 event.pdf
API 101 event.pdf
 
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)
대용량 로그분석 Bigquery로 간단히 사용하기 (20170215 T아카데미)
 
API Design- Best Practices
API Design-   Best PracticesAPI Design-   Best Practices
API Design- Best Practices
 
elasticsearch_적용 및 활용_정리
elasticsearch_적용 및 활용_정리elasticsearch_적용 및 활용_정리
elasticsearch_적용 및 활용_정리
 
REST-API design patterns
REST-API design patternsREST-API design patterns
REST-API design patterns
 

Similar to Stop the noise! - Introduction to the JSON:API specification in Drupal

Data models in Angular 1 & 2
Data models in Angular 1 & 2Data models in Angular 1 & 2
Data models in Angular 1 & 2Adam Klein
 
Solutions for bi-directional Integration between Oracle RDMBS & Apache Kafka
Solutions for bi-directional Integration between Oracle RDMBS & Apache KafkaSolutions for bi-directional Integration between Oracle RDMBS & Apache Kafka
Solutions for bi-directional Integration between Oracle RDMBS & Apache KafkaGuido Schmutz
 
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...confluent
 
Solutions for bi-directional integration between Oracle RDBMS & Apache Kafka
Solutions for bi-directional integration between Oracle RDBMS & Apache KafkaSolutions for bi-directional integration between Oracle RDBMS & Apache Kafka
Solutions for bi-directional integration between Oracle RDBMS & Apache KafkaGuido Schmutz
 
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)Pat Patterson
 
Java Script Based Client Server Webapps 2
Java Script Based Client Server Webapps 2Java Script Based Client Server Webapps 2
Java Script Based Client Server Webapps 2kriszyp
 
RESTful JSON web databases
RESTful JSON web databasesRESTful JSON web databases
RESTful JSON web databaseskriszyp
 
Python RESTful webservices with Python: Flask and Django solutions
Python RESTful webservices with Python: Flask and Django solutionsPython RESTful webservices with Python: Flask and Django solutions
Python RESTful webservices with Python: Flask and Django solutionsSolution4Future
 
Using Sinatra to Build REST APIs in Ruby
Using Sinatra to Build REST APIs in RubyUsing Sinatra to Build REST APIs in Ruby
Using Sinatra to Build REST APIs in RubyLaunchAny
 
Elasticsearch in 15 Minutes
Elasticsearch in 15 MinutesElasticsearch in 15 Minutes
Elasticsearch in 15 MinutesKarel Minarik
 
Graph Analysis over JSON, Larus
Graph Analysis over JSON, LarusGraph Analysis over JSON, Larus
Graph Analysis over JSON, LarusNeo4j
 
Rspec API Documentation
Rspec API DocumentationRspec API Documentation
Rspec API DocumentationSmartLogic
 
FamilySearch Reference Client
FamilySearch Reference ClientFamilySearch Reference Client
FamilySearch Reference ClientDallan Quass
 
Introduction to MongoDB and Workshop
Introduction to MongoDB and WorkshopIntroduction to MongoDB and Workshop
Introduction to MongoDB and WorkshopAhmedabadJavaMeetup
 
Semantic Web & TYPO3
Semantic Web & TYPO3Semantic Web & TYPO3
Semantic Web & TYPO3André Wuttig
 

Similar to Stop the noise! - Introduction to the JSON:API specification in Drupal (20)

Data models in Angular 1 & 2
Data models in Angular 1 & 2Data models in Angular 1 & 2
Data models in Angular 1 & 2
 
Solutions for bi-directional Integration between Oracle RDMBS & Apache Kafka
Solutions for bi-directional Integration between Oracle RDMBS & Apache KafkaSolutions for bi-directional Integration between Oracle RDMBS & Apache Kafka
Solutions for bi-directional Integration between Oracle RDMBS & Apache Kafka
 
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...
Solutions for bi-directional integration between Oracle RDBMS and Apache Kafk...
 
Solutions for bi-directional integration between Oracle RDBMS & Apache Kafka
Solutions for bi-directional integration between Oracle RDBMS & Apache KafkaSolutions for bi-directional integration between Oracle RDBMS & Apache Kafka
Solutions for bi-directional integration between Oracle RDBMS & Apache Kafka
 
Ams adapters
Ams adaptersAms adapters
Ams adapters
 
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)
OData: Universal Data Solvent or Clunky Enterprise Goo? (GlueCon 2015)
 
Java Script Based Client Server Webapps 2
Java Script Based Client Server Webapps 2Java Script Based Client Server Webapps 2
Java Script Based Client Server Webapps 2
 
Postman On Steroids
Postman On SteroidsPostman On Steroids
Postman On Steroids
 
RESTful JSON web databases
RESTful JSON web databasesRESTful JSON web databases
RESTful JSON web databases
 
Python RESTful webservices with Python: Flask and Django solutions
Python RESTful webservices with Python: Flask and Django solutionsPython RESTful webservices with Python: Flask and Django solutions
Python RESTful webservices with Python: Flask and Django solutions
 
Using Sinatra to Build REST APIs in Ruby
Using Sinatra to Build REST APIs in RubyUsing Sinatra to Build REST APIs in Ruby
Using Sinatra to Build REST APIs in Ruby
 
Elasticsearch in 15 Minutes
Elasticsearch in 15 MinutesElasticsearch in 15 Minutes
Elasticsearch in 15 Minutes
 
Workshop 17: EmberJS parte II
Workshop 17: EmberJS parte IIWorkshop 17: EmberJS parte II
Workshop 17: EmberJS parte II
 
JS-05-Handlebars.ppt
JS-05-Handlebars.pptJS-05-Handlebars.ppt
JS-05-Handlebars.ppt
 
Graph Analysis over JSON, Larus
Graph Analysis over JSON, LarusGraph Analysis over JSON, Larus
Graph Analysis over JSON, Larus
 
Elastic tire demo
Elastic tire demoElastic tire demo
Elastic tire demo
 
Rspec API Documentation
Rspec API DocumentationRspec API Documentation
Rspec API Documentation
 
FamilySearch Reference Client
FamilySearch Reference ClientFamilySearch Reference Client
FamilySearch Reference Client
 
Introduction to MongoDB and Workshop
Introduction to MongoDB and WorkshopIntroduction to MongoDB and Workshop
Introduction to MongoDB and Workshop
 
Semantic Web & TYPO3
Semantic Web & TYPO3Semantic Web & TYPO3
Semantic Web & TYPO3
 

Recently uploaded

Sample pptx for embedding into website for demo
Sample pptx for embedding into website for demoSample pptx for embedding into website for demo
Sample pptx for embedding into website for demoHarshalMandlekar2
 
Developer Data Modeling Mistakes: From Postgres to NoSQL
Developer Data Modeling Mistakes: From Postgres to NoSQLDeveloper Data Modeling Mistakes: From Postgres to NoSQL
Developer Data Modeling Mistakes: From Postgres to NoSQLScyllaDB
 
Nell’iperspazio con Rocket: il Framework Web di Rust!
Nell’iperspazio con Rocket: il Framework Web di Rust!Nell’iperspazio con Rocket: il Framework Web di Rust!
Nell’iperspazio con Rocket: il Framework Web di Rust!Commit University
 
SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024Lorenzo Miniero
 
Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 3652toLead Limited
 
What is DBT - The Ultimate Data Build Tool.pdf
What is DBT - The Ultimate Data Build Tool.pdfWhat is DBT - The Ultimate Data Build Tool.pdf
What is DBT - The Ultimate Data Build Tool.pdfMounikaPolabathina
 
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek SchlawackFwdays
 
A Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersA Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersNicole Novielli
 
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxUse of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxLoriGlavin3
 
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...AliaaTarek5
 
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)Mark Simos
 
"ML in Production",Oleksandr Bagan
"ML in Production",Oleksandr Bagan"ML in Production",Oleksandr Bagan
"ML in Production",Oleksandr BaganFwdays
 
The State of Passkeys with FIDO Alliance.pptx
The State of Passkeys with FIDO Alliance.pptxThe State of Passkeys with FIDO Alliance.pptx
The State of Passkeys with FIDO Alliance.pptxLoriGlavin3
 
Take control of your SAP testing with UiPath Test Suite
Take control of your SAP testing with UiPath Test SuiteTake control of your SAP testing with UiPath Test Suite
Take control of your SAP testing with UiPath Test SuiteDianaGray10
 
Digital Identity is Under Attack: FIDO Paris Seminar.pptx
Digital Identity is Under Attack: FIDO Paris Seminar.pptxDigital Identity is Under Attack: FIDO Paris Seminar.pptx
Digital Identity is Under Attack: FIDO Paris Seminar.pptxLoriGlavin3
 
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024BookNet Canada
 
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024BookNet Canada
 
Generative AI for Technical Writer or Information Developers
Generative AI for Technical Writer or Information DevelopersGenerative AI for Technical Writer or Information Developers
Generative AI for Technical Writer or Information DevelopersRaghuram Pandurangan
 
What's New in Teams Calling, Meetings and Devices March 2024
What's New in Teams Calling, Meetings and Devices March 2024What's New in Teams Calling, Meetings and Devices March 2024
What's New in Teams Calling, Meetings and Devices March 2024Stephanie Beckett
 
"Debugging python applications inside k8s environment", Andrii Soldatenko
"Debugging python applications inside k8s environment", Andrii Soldatenko"Debugging python applications inside k8s environment", Andrii Soldatenko
"Debugging python applications inside k8s environment", Andrii SoldatenkoFwdays
 

Recently uploaded (20)

Sample pptx for embedding into website for demo
Sample pptx for embedding into website for demoSample pptx for embedding into website for demo
Sample pptx for embedding into website for demo
 
Developer Data Modeling Mistakes: From Postgres to NoSQL
Developer Data Modeling Mistakes: From Postgres to NoSQLDeveloper Data Modeling Mistakes: From Postgres to NoSQL
Developer Data Modeling Mistakes: From Postgres to NoSQL
 
Nell’iperspazio con Rocket: il Framework Web di Rust!
Nell’iperspazio con Rocket: il Framework Web di Rust!Nell’iperspazio con Rocket: il Framework Web di Rust!
Nell’iperspazio con Rocket: il Framework Web di Rust!
 
SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024SIP trunking in Janus @ Kamailio World 2024
SIP trunking in Janus @ Kamailio World 2024
 
Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365Ensuring Technical Readiness For Copilot in Microsoft 365
Ensuring Technical Readiness For Copilot in Microsoft 365
 
What is DBT - The Ultimate Data Build Tool.pdf
What is DBT - The Ultimate Data Build Tool.pdfWhat is DBT - The Ultimate Data Build Tool.pdf
What is DBT - The Ultimate Data Build Tool.pdf
 
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
"Subclassing and Composition – A Pythonic Tour of Trade-Offs", Hynek Schlawack
 
A Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software DevelopersA Journey Into the Emotions of Software Developers
A Journey Into the Emotions of Software Developers
 
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptxUse of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
Use of FIDO in the Payments and Identity Landscape: FIDO Paris Seminar.pptx
 
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...
(How to Program) Paul Deitel, Harvey Deitel-Java How to Program, Early Object...
 
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)
Tampa BSides - Chef's Tour of Microsoft Security Adoption Framework (SAF)
 
"ML in Production",Oleksandr Bagan
"ML in Production",Oleksandr Bagan"ML in Production",Oleksandr Bagan
"ML in Production",Oleksandr Bagan
 
The State of Passkeys with FIDO Alliance.pptx
The State of Passkeys with FIDO Alliance.pptxThe State of Passkeys with FIDO Alliance.pptx
The State of Passkeys with FIDO Alliance.pptx
 
Take control of your SAP testing with UiPath Test Suite
Take control of your SAP testing with UiPath Test SuiteTake control of your SAP testing with UiPath Test Suite
Take control of your SAP testing with UiPath Test Suite
 
Digital Identity is Under Attack: FIDO Paris Seminar.pptx
Digital Identity is Under Attack: FIDO Paris Seminar.pptxDigital Identity is Under Attack: FIDO Paris Seminar.pptx
Digital Identity is Under Attack: FIDO Paris Seminar.pptx
 
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
New from BookNet Canada for 2024: BNC CataList - Tech Forum 2024
 
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
Transcript: New from BookNet Canada for 2024: Loan Stars - Tech Forum 2024
 
Generative AI for Technical Writer or Information Developers
Generative AI for Technical Writer or Information DevelopersGenerative AI for Technical Writer or Information Developers
Generative AI for Technical Writer or Information Developers
 
What's New in Teams Calling, Meetings and Devices March 2024
What's New in Teams Calling, Meetings and Devices March 2024What's New in Teams Calling, Meetings and Devices March 2024
What's New in Teams Calling, Meetings and Devices March 2024
 
"Debugging python applications inside k8s environment", Andrii Soldatenko
"Debugging python applications inside k8s environment", Andrii Soldatenko"Debugging python applications inside k8s environment", Andrii Soldatenko
"Debugging python applications inside k8s environment", Andrii Soldatenko
 

Stop the noise! - Introduction to the JSON:API specification in Drupal

  • 1. Stop the noise! Introduction to the JSON:API specification Björn Brala – Technical Director @swis.nl
  • 2. Before we start -Feel free to ask questions! -https://swis.nl/drupaljam -This presentation -All mentioned links (and more)
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 10. CRM ERP FIN Clients Employees (Back office) An optimal digital experience. Always and everywhere.
  • 11. CRM ERP FIN Clients Employees (Back office) An optimal digital experience. Always and everywhere.
  • 12. CRM ERP FIN Clients Employees (Back office) An optimal digital experience. Always and everywhere.
  • 14.
  • 15.
  • 16. If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can be your anti- bikeshedding tool.
  • 18. Any colour will do, really…
  • 19. What is JSON:API XML! JSON No nesting MyREST oData
  • 24. History of {JSON:API} - Embed.js creator - Rust Core Team - Retired Ruby on Rails and jQuery core teams. - ECMAScript's TC39 standards committee member - W3C's TAG (Technical Architecture Group) memberYehuda Katz
  • 25. Eliminate the need for ad-hoc code per application to communicate with servers that communicate in a well-defined way.
  • 28. 150+ client and server implementations available in about 20 different languages Is it used?
  • 30. Drupal jsonapi module • 2016 Started by Mateu Aguiló Bosch (e0ipso – eh-oh-ipso) • 2017 Release 1.0 • 2017 Aquia provided Wim Leers and Gabe Sollice • 2019 januari Release 2.0 • 2019 march Committed to core! • 28 months, 450 commits, 32 releases and 5,500 test runs.
  • 31. Core concepts of JSON:API
  • 32. Core concepts of JSON:API -Uses basic HTTP - GET, POST, PATCH, DELETE -Response in JSON - Content type: application/vnd.api+json
  • 33. Basic HTTP request - Core concepts of JSON:API GET /articles HTTP/1.1 Accept: application/vnd.api+json
  • 34. JSON:API document - Core concepts of JSON:API { data: { type: "node--article", id: "d71db11d-ceef-401f-b340-f0ac1a877dfd", attributes: { title: “Stop the noise!“ }, relationships: { uid: { data: { type: "user--user", id: "c47322d3-2131-474b-a724-444acf33648b", }, links: { self: "https://example.com/jsonapi/node/article/d71../relationships/uid", related: "https://example.com/jsonapi/node/article/d71../uid" } } }, links: { self: "https://example.com/jsonapi/node/article/d71..." } }, // ...
  • 36. Compound documents To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called “compound documents”.
  • 37. Example - Compound documents { "data": [ { "type": "articles", "id": "1", "attributes": { "title": "JSON API paints my bikeshed!" }, "links": {...}, "relationships": { “comments": { "links": {...}, "data": { "type": “comments", "id": “5" } } } } ], "included": [...] }
  • 38. Example - Compound documents { "data": [...], "included": [ { "type": “comments", "id": “5", "attributes": { “body": “first!" }, "relationships": { “author": { "data": { "type": “people", "id": “2" } } } "links": { "self": "http://example.com/comments/9" } } ] }
  • 39. Inclusion of related resources
  • 40. Inclusion of related resources GET /articles/1?include=author HTTP/1.1 Accept: application/vnd.api+json
  • 41. Inclusion of related resources GET /articles/1?include=author,comments HTTP/1.1 Accept: application/vnd.api+json
  • 42. Inclusion of related resources GET /articles/1?include=author,comments.author HTTP/1.1 Accept: application/vnd.api+json
  • 46. Filtering The filter query parameter is reserved for filtering data. Servers and clients SHOULD use this key for filtering operations.
  • 48. Filtering in Drupal GET /articles?filter[field_name]=value&filter[field_other]=value HTTP/1.1 Accept: application/vnd.api+json
  • 49. Short and normal - Filtering in Drupal SHORT: ?filter[field_first_name]=Janis NORMAL: ?filter[a-label][condition][path]=field_first_name &filter[a-label][condition][operator]=%3D (an encoded ‘=‘) &filter[a-label][condition][value]=Janis
  • 50. Features - Filtering in Drupal -Supported operators -Condition grouping -Paths
  • 51. - Filtering in Drupal ?filter[first_name_filter][condition][path]=field_first_name &filter[first_name_filter][condition][operator]=%3D &filter[first_name_filter][condition][value]=Janis DrupaljsonapiQueryEntityCondition::$allowedOperators = [ '=', '<>', // Equals '>', '>=', '<', '<=', // Greater or less than 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison 'IN', 'NOT IN', // Value in set 'BETWEEN', 'NOT BETWEEN', // Range comparison 'IS NULL', 'IS NOT NULL', // NULL comparison ]; Supported operators
  • 52. Supported operators - Filtering in Drupal ?filter[first_name_filter][condition][path]=field_first_name &filter[first_name_filter][condition][operator]=STARTS_WITH &filter[first_name_filter][condition][value]=J DrupaljsonapiQueryEntityCondition::$allowedOperators = [ '=', '<>', // Equals '>', '>=', '<', '<=', // Greater or less than 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison 'IN', 'NOT IN', // Value in set 'BETWEEN', 'NOT BETWEEN', // Range comparison 'IS NULL', 'IS NOT NULL', // NULL comparison ];
  • 53. Supported operators - Filtering in Drupal ?filter[first_name_filter][condition][path]=field_first_name &filter[first_name_filter][condition][operator]=IN &filter[first_name_filter][condition][value][]=Janice &filter[first_name_filter][condition][value][]=John &filter[first_name_filter][condition][value][]=Jeff DrupaljsonapiQueryEntityCondition::$allowedOperators = [ '=', '<>', // Equals '>', '>=', '<', '<=', // Greater or less than 'STARTS_WITH', 'CONTAINS', 'ENDS_WITH', // String comparison 'IN', 'NOT IN', // Value in set 'BETWEEN', 'NOT BETWEEN', // Range comparison 'IS NULL', 'IS NOT NULL', // NULL comparison ];
  • 54. Features - Filtering in Drupal -Supported operators -Condition grouping -Paths
  • 55. Condition grouping - Filtering in Drupal Show me the users that have the job developer and have the first or last name ‘smith’.
  • 56. Condition grouping - Filtering in Drupal ?filter[or_group][group][conjunction]=OR &filter[first_name_filter][condition][path]=field_first_name &filter[first_name_filter][condition][value]=smith &filter[first_name_filter][condition][memberOf]=or_group &filter[last_name_filter][condition][path]=field_last_name &filter[last_name_filter][condition][value]=smith &filter[last_name_filter][condition][memberOf]=or_group &filter[job_filter][condition][path]=job &filter[job_filter][condition][value]=developer
  • 57. Features - Filtering in Drupal -Supported operators -Condition grouping -Paths
  • 58. Condition grouping - Filtering in Drupal ?filter[career][condition][path]=field_career.name &filter[career][condition][operator]=%3D &filter[career][condition][value]=Rockstar
  • 61. Examples - Filtering in Drupal SHORT filter[uid.name][value]=admin NORMAL filter[name-filter][condition][path]=uid.name filter[name-filter][condition][value]=admin Get nodes created by user admin
  • 62. Examples - Filtering in Drupal SHORT filter[title][operator]=CONTAINS&filter[title][value]=Foo NORMAL filter[title-filter][condition][path]=title filter[title-filter][condition][operator]=CONTAINS filter[title-filter][condition][value]=Foo Filter nodes where ‘title’ contains ‘Foo’
  • 63. Examples - Filtering in Drupal FILTER BY LOCALITY filter[field_address][condition][path]=field_address.locality filter[field_address][condition][value]=Mordor FILTER BY ADDRESS LINE filter[field_address][condition][path]=field_address.address_line1 filter[field_address][condition][value]=Rings Street Filter by non-standard complex field
  • 66. The Drupal way - Sorting SHORT: ?sort=uid.name,-created NORMAL: ?sort[sort-created][path]=created &sort[sort-created][direction]=DESC &sort[sort-author][path]=uid.name
  • 68. Filtering A server MAY provide links to traverse a paginated data set (“pagination links”). The page query parameter is reserved for pagination. Servers and clients SHOULD use this key for pagination operations.
  • 70. Pagination in Drupal { "data": [ {"type": "sample--type", "id": "abcd-uuid-here"}, {"type": "sample--type", "id": "efgh-uuid-here"}, {"type": "sample--type", "id": "ijkl-uuid-here"} ], "links": { "self": "<collection_url>?page[offset]=1&page[limit]=3", "next": "<collection_url>?page[offset]=2&page[limit]=3", "prev": "<collection_url>?page[offset]=0&page[limit]=3" } }
  • 71. Limits - Pagination -Maximum page limit of 50 -No pagecount available
  • 72. Creating, updating and deleting resources
  • 73. Creating resources { "data": { "type": "photos", "attributes": { "title": "Ember Hamster", "src": "http://example.com/images/productivity.png" }, "relationships": { "photographer": { "data": { "type": "people", "id": "9" } } } } } POST /photos HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json
  • 74. Creating resources { "data": { "type": "photos", "id": "550e8400-e29b-41d4-a716-446655440000", "attributes": { "title": "Ember Hamster", "src": "http://example.com/images/productivity.png" }, "relationships": { "photographer": { "data": { "type": "people", "id": "9" } } } } } HTTP/1.1 201 Created Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000 Content-Type: application/vnd.api+json
  • 75. Updating resources { "data": { "type": "articles", "id": "1", "attributes": { "title": "To TDD or Not" } } } PATCH /articles/1 HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json
  • 76. Updating resource relations { "data": { "type": "articles", // ... "relationships": { "author": { "data": { "type": "people", "id": "1" } }, "tags": { "data": [ { "type": "tags", "id": "2" }, { "type": "tags", "id": "3" } ] }, "comments": { "data": [] } } } } PATCH /articles/1 HTTP/1.1 Content-Type: application/vnd.api+json Accept: application/vnd.api+json
  • 77. Deleting resources DELETE /articles/1 HTTP/1.1 Accept: application/vnd.api+json
  • 78. What did we learn today?
  • 79. What did we learn today? -Documents structure -Limit data in responses -Manipulate data
  • 80.
  • 81.
  • 84. • Presentation, these links and more • https://swis.nl/drupaljam • Leave your email theres • Slack • #jsonapi and #contenta • JSON:API specification • https://jsonapi.org • Drupal’s great JSON:API documentation • https://www.drupal.org/docs/8/modules/jsonapi • API first initiative • https://www.drupal.org/about/strategic-initiatives/api-first Questions?

Editor's Notes

  1. - Before we start, please feel free to ask questions at any point. - Check out https://swis.nl/drupaljam for this presentation and all mentioned links.
  2. - Hi everyone, my name is Björn Brala, technical director at SWIS. - I live in Leiden in the Netherlands with my 3 cats, wife and daughter, of 4.
  3. - I started developing for the web back in 2003 when frames were fine and flash was cool. I’ve been involved with the web since then.
  4. I started using Drupal when 8 was in beta. The modernization of Drupal sounded like a giant leap forwards.
  5. - Fast forward to now, I work at SWIS as technical director. - SWIS creates digital experiences and supports Drupal, Laravel and multiple front-end frameworks. Our client base spans multiple sectors and sizes. Getting the communication between different systems right is essential in creating sustainable architectures.
  6. We create our converting websites in Drupal, most of the time. Nowadays in order to create a complete digital experience you need to connect to multiple systems to make sure online transactions go smoothly.
  7. Integration of systems as the CRM, ERP or financial software of a company streamline the workflow of the employees and customer journey of clients.
  8. We mostly use Laravel and VueJS to create custom applications or tools that solve specific business needs for our clients, we always try to use the right tool for the job. Going forward from this architecture we create a platform where we can help our clients create an optimal digital experience.
  9. Experiences aren’t limited to just single websites anymore. You could have a normal Drupal website as your corporate site, SPA’s to help your clients on the go, native applications or even API’s to let your clients create more value for your business.
  10. We aren’t just using computers anymore. Mobile, voice, IOT devices, VR all are a part of the online landscape. We combine these tools to create an optimal digital experience for our clients AND their clients.
  11. So I say; Stop the noise! We should stop talking about how we communicate and talk about what we communicate. This is where JSON:API comes in.
  12. On the homepage of JSON:API they say: If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON:API can be your anti-bikeshedding tool. You might think, bikeshedding? What?
  13. Back in the 50’s a guy named Parkinson made the argument that members of an organization give to much weight to trivial issues. Like when approving plans for a powerplant, discuss what color and material should the bikeshed be. This eventually led to the term bikeshedding, where we spend to much time discussing the wrong things. I see this happen all the time. Getting interop right between multiple teams and systems is hard. But a lot of time is wasted talking about the way systems should communicate.
  14. So, guys, stop talking about the color of your bikeshed… any colour will do… really. We love our jobs, we love talking about architectures, we love talking about innovative solutions to problems. I mean, connecting multiple systems is fun!
  15. Discussing the structure of an API for the gazilionth time, not so fun.
  16. JSON:API solves this problem by defining a generic format for all your API responses. No need to talk about the structure, or write a new API client for every new service. And we can go back to focusing on what we love. Solving new problems.
  17. I’m going to start with a introduction on how JSON:API came to be and how it ended up in Drupal core.
  18. JSON:API was originally drafted by Yehuda Katz in May 2013.
  19. JSON:API was originally drafted by Yehuda Katz in May 2013. Embed.js creator Rust Core Team Retired Ruby on Rails and jQuery core teams. ECMAScript's TC39 standards committee member W3C's TAG (Technical Architecture Group) member This first draft was extracted from the JSON transport implicitly defined by Ember Data’s REST adapter.
  20. Eliminate the need for ad-hoc code per application to communicate with servers that communicate in a well-defined way. In general the goal of Embed Data was; you should not require ad-hoc code per application to communicate with servers. In the next 2 years they worked quite hard to get the spec complete, and in may 2015 the first 1.0 version was released. What I find so awesome is that the specification was not crafted in some small backroom in an office, but extracted from solving real life problems and iterating on those solutions. I feel this is the best kind of spec.
  21. A specification is only really viable if it is used in real life. You can’t reap much benefits of a specification if you are the sole user. There are quite a few companies already using the spec publicly. Ignoring the fact that every up-to-date Drupal site is a possible implementation.
  22. Netflix has publishes an extremely fast JSON:API serializer for Ruby. Hinting at usage internally. Fitbit uses it in exposing a Friends Web API and an ex employee did a presentation on how JSON:API helped Fitbit in smoothing out interservice communication internally. G2 crowd; a site to compare software solutions uses it for their Data API. The Apple Store Connect API, released in 2018, uses the JSON:API spec to help developers automate their development cycle. KFC UK is currently building a new site, where all content will be loaded from Drupal JSON:API. So even the bigger companies are embracing JSON:API as a way to be more efficient in publishing API’s and even using Drupal to do so!
  23. There are about 150+ client and server implementations listed on jsonapi.org, available in about 20 different languages! In regards to Drupal the client implementations can help you fetch your data into a wide array of languages and frameworks. Of all the server implementation Drupal’s implementation is the most complete available.
  24. Drupal has the best server-implementation of JSON:API available. Rome wasn’t build in one day, a small history of the module.
  25. In 2016 guy named Mateu Aguiló Bosch (e0ipso, eh-oh-ipso) In 2016 he started working on a JSON:API contrib module and he released version 1.0 in may 2017. Around mid 2016 Dries started floating the idea of JSON:API being part of Drupal core. This changed to a recommendation at the end of 2016. A year later Win Leers and Gabe Sullice were assigned to the JSON:API module by Aquia and started devoting most of their time on getting it ready for core. This work resulted in a 2.0 release at the beginning of this year. This marked the start of the module’s move to Drupal core. 2 months ago, the time was nigh! And JSON:API released in Drupal 8.7! So from beginning to end, it took 28 months, 450 commits, 32 releases and more than 5,500 test runs. Pretty impressive really.
  26. So lets get to the good stuff. Lets talk about the specification.
  27. So lets get to the good stuff. Lets talk about the specification. JSON:API uses basic HTTP for communication. The HTTP method defines what want action to take. Just basic GET, POST, PATCH and DELETE requests. The API responds in JSON, with a specific header for the content type. This means JSON:API is pretty easy to integrate in an existing hosting platform and automatically makes use of any optimizations you might have implemented. Such as caching, load balancing or other basic http optimizations.
  28. This is an example of a simple get request. It calls /articles with an proper accept header. This will result in a list of documents.
  29. The response such a request is a simple JSON document with the information for that entity. You see the article with its attributes. You see the relationships for this entity in the relation tag. This contains the basic relation and reference to that entity. Note there is no data of that relation available here. Using the links in the document you can retrieve information for related resources. But this is only scratching the surface. There are quite a few features which make JSON:API such a lovely spec to use.
  30. So, next up are “compound documents”. These are defined as;
  31. To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called “compound documents”. That sound pretty awesome right? So, a compound document is a response which includes the data of all included resources. For example, when requesting an article it may include the data of the author and all related comments for that article. This is awesome for a few reasons. Getting the full data of a resource you want to consume in one go is unheard of unless specific endpoints are programmed. On the server side of things, caching and invalidating requests like this is easy-peasy!
  32. Let’s have a better look at a compound document. A compound document adds an ‘included’ property to the response. This property contains an array of documents of all the relations. So here we have an article which contains a comment with id 5. Let’s have a look at the include.
  33. There you have it, the related comment to this article. The structure is exactly the same. Some things to note though. It might feel weird for the JSON to only refer to the comment as an ID and storing the data in the included tag. But imagine this being an author. Multiple articles might refer to the same author, this way JSON:API only send the data of the author once. Pretty efficient 😊 When you start retrieving large lists of articles, the includes will get of hand pretty fast. If you load 10 articles, all with references to taxonomy, users, comments or more. Your document will get HUGE.
  34. You don’t always want everything. Sometimes you just need the related author and certain taxonomy should be kept on the server. In order to de-bloat your request you can specify what relations you want by using the ‘include’ parameter.
  35. So here you see I am retrieving an article with only the author included. In the document every other relation is now only referenced by their id with a link.
  36. This parameter is pretty flexible, if you need more than one include you can just add more relations comma separated. So now we have the author and comments for this article. But that’s not all. What if we need to go even deeper. Comments have related authors also.
  37. You can include nested relations with ease using a dot-notation. So adding `comments.author` will include all the authors of the related comments. This level of flexibility makes retrieving the correct information in one go a breeze.
  38. As I said earlier, if you are fetching data from a JSON:API your request can get large fast. Especially when the included relationships contain a lot of data. Most of the time you do not need every single attribute defined in the resource but only want the things like author names and titles. JSON:API provides sparse fieldsets for this usecase.
  39. You use sparse fieldsets with the fields parameter. The key of the parameter is the resource-type and the value is the field you want to retrieve. You can specify the fields once for every type of resource you fetch.
  40. So we’ve talked about fetching documents. We talked about slimming down the content of the documents. But what if we need filtering of collections.
  41. The filter query parameter is reserved for filtering data. Servers and clients SHOULD use this key for filtering operations. Well, JSON:API only reserves the parameter and the server can decide how to filter. Ok, that is fine I guess. Lets try that again.
  42. The filter implementation of Drupal is extremely powerful. This does there a slight learning curve. Lets start simple.
  43. The simplest, most common filter is a key-value filter. Pretty basic stuff. You can add any amount of filters. Drupal support 2 ways of writing filters. This is the short syntax, but if you want more control you can use, what Drupal defines as, the normal syntax.
  44. Here we give the filter a-label and we split the path, operator and value into their own parameter. The path is the field we are filtering on. The operator describes how we compare the value and the value is the thing you compare against. The label is essentially needed to group these 3 parameters together. Make sure your identifiers are unique. For a normal key-value filter this doesn’t do much. But it opens up a plethora of possibilities later down the line. For example this way you can have full control on the operator.
  45. The filtering system supports multiple operators, grouping of filters to control conjunctions (AND/OR) and paths to define what to filter on. Let’s have a closer look at these parts.
  46. The operator controls describes how we compare the value. We have quite a lot available, looking at the source the current set supports all the operators you might need. We have the basics, like equals, greatest/less than. But also string, range, set and NULL comparison.
  47. So for example if you want to find all users with a first name starting with a “J” you would use STARTS_WITH. So the operator is STARTS_WITH and the value should be “J”. Every condition that compares to a single value works like this. Just set the operator and value and you are good to go.
  48. Not every operators compared to a single value. We need a way to send multiple values to the system. We do this by making the value parameter an array. Lets try finding users with a few different names. For this we use the IN operator and send the names we want to match on as an array. This would match all users where the first name is either Janice, John or Jeff. You should use this syntax for the ‘value in set’ and `range` operators.
  49. So, that’s about it for the operators. Next up is condition grouping. Consider the following question:
  50. Show me the users that have the job developer and have the first or last name ‘smith’. In order to get that working we need a way to query firstname = smith OR last name = smith grouped together. For this we need to create a condition group. A condition group is a set of conditions with a set conjunction. This can be either AND or OR.
  51. So this is such a group, a group starts with a label. This label is important because we refer to this label in our conditions. We tell the API we are defining a group with the conjunction OR. After defining the group we can add conditions to this group. We use the memberOf property for that. This means that every condition that is a member of the group with use the conjunction defined in that group. So, quick question; Who notices something missing in this example? … The operator is missing! The thing is, the default operator is equals, so you so not need to write the equals operator. There are a few shortcuts hidden in the Drupal implementation, you’ll find those in the docs on Drupal.org. Hopefully you are understand how the grouping helps you create filters. We will look at some more real life examples later on.
  52. Next up, paths. In our examples we see path used to communicate the field which we need to filter.
  53. Earlier, when we talked about includes I showed you the dot notation to refer to nested relations. Paths can do the same. So for example, we have a users career stored as a separate resource. This means if we want to filter on the name of the career we need to refer to it as field_career.name. This same technique is used for fields that might store sub-properties. So if we think about a phone field, it could have a country-code attached to it. This extends to other fields also, an url could have an uri and url.
  54. This is a lot to process, to give you a bit more feeling for how you would use this in the real world I’ll quick run through some common examples from the documentation.
  55. This one is quite simple, just filter on status = 1
  56. A lot of time you want to filter by a reference to an entity. In this care the username. You can nest the name through uid.
  57. We’ve seen the CONTAINS operator, but here you can compare the short and normal version. In the short version the field is the key, in the normal version we label the condition so we can group is later.
  58. Some fields contain multiple values, in this example you see an address field. You can filter by locality or address line quite easily using the same syntax as with relations.
  59. By now we are quite capable of selecting the right set of documents, and trimming down the data to what we need. But you might want to sort your documents in a more sane order. This could be as simple as sorting by created date, but this can be any number of parameters really.
  60. So let’s start simple, sorting is done by using the sort parameters. Sorting by a field is done by using… ?sort=created By default the parameters are sorted ascending, so unless you want the oldest record first, this is rather useless. In order to reverse the order you can just add a minus sight to it. ?sort=-created This way the newest record will be first, and you can compile a list of latest articles for example. The sort parameter accepts multiple values, separated by a comma. So, to ask the API to order by author, then created date descending we use; ?sort=author,-created So that is basic sorting. Up until now pretty much every parameter you can fill with a field also accepts the value inside a relation. This is also true for the sort parameter. For example in Drupal when you like to sort by the author name you would use: ?sort=uid.name,-created This fetches the relation and sorts by related data.
  61. Since the Drupal implementation uses the same parameter-parsing as with filtering it is also possible to write a NORMAL version or the sort parameter. Though I cannot really find much reason to use that unless it’s easier for your client to generate. For now it does not support any more features than the SHORT version.
  62. Next up, pagination. You really do need to limit your collection results to sensible amounts.
  63. A server MAY provide links to traverse a paginated data set (“pagination links”). The page query parameter is reserved for pagination. Servers and clients SHOULD use this key for pagination operations. There is a pattern here…
  64. So the specification says you may use the ‘page’ parameter to paginate collections. It doesn’t care how you implement this. It does suggests some strategies. Let’s have a look at how Drupal implemented pagination.
  65. Lets have a look at a basic example of a paginated response. There is a few things of note in this response. There are 3 pagination links in the links property. Self: current url Next: next page Prev: previous page. There is also a page[limit] set to 3 in the links. It’s important to note that the existence of the pagination links is relevant. Next: if it exists, there are more pages. Next: doesn’t exist, there are no mote pages. If prev doesn’t exist then you are on the first page. If neither next or prev exists, you are on the only page. So the response does inform you completely about the state of the pagination.
  66. There are a few gotcha’s in relation to pagination. Maximum page limit 50: To limit possibilities of DDOS’in, the limit is set to 50 a page. When a response is uncached the module has to do an access check of all resources. This means if someone would set the limit to something insane, like 200k, its quite easy to break the server. No pagecount in response: The pagecount is not available for performance reasons. It would need to calculate the pagecount for every request and considering the access checks, this will result in unwanted load.
  67. When you understand the structure of JSON:API documents, creating and updating resources is a breeze. It uses the standard HTTP verbs to communicate the desired action of the request. GET for fetching, POST for creating, PATCH for (partial) updating and DELETE for deleting resources.
  68. To create a resource in JSON:API you send a complete document to the server through POST. This document looks the same as you normally receive when retrieving data, but you skip adding the ID. You should notice the relations to other types is includes directly in the payload.
  69. The API communicates if the creation was an success through the response code. The body of the response contains the resource you just created, this will help you add the appropriate ID that is generated server side.
  70. To update resources you send a patch request to an single resource. This request overwrites all attributes specified in the payload. So that is quite important to note, the patch request does not empty values, unless an attribute is specified as empty.
  71. Patch requests can also be used to update the relations of a resource. There is a difference in how you update the different kind of relations. Author is a to-one relation. There we send the data with the relation directly. Tags is a to-many relation. We now send a complete set of new tags to the article. This means it overwrites all other relations that might be present at the moment. I will note that it is possible to add and delete single relations by using that specific relations endpoint. But I won’t be going into that today. Comments is a to many relationship and this request clears the relation to all comment for the article.
  72. For sake of completing all CRUD operation, I’ll show the DELETE operator. Nothing more than sending a delete to the endpoint of a single resource. The response code communicates if the operation was successful.
  73. This is just about everything I want to tell about the specification and it’s usage today.
  74. We talked about the document structure, compound documents, relations. We had a good look at how we can limit the data usage by using sparse fieldsets, includes, filters and pagination. Last but not least we’ve looked at how to manipulate resources through POST, PATCH and DELETE. You should have a good overview by now how JSON:API can help you communicate efficiently between services.
  75. I love the structure, extreme consistency and built in flexibility of JSON:API. It really tickles my developers hearth. This consistency makes it the perfect fit for Drupal. The way Drupal handles nodes, relations and caching makes it that the data can slot into the spec perfectly. Reflecting the data model beautifully in JSON. Since Drupal is now shipping with JSON:API available for every… single... site with zero configuration. I feel this will start a new era where Drupal will gain more and more ground being the go-to headless CMS. Let’s work together to ‘Stop the noise’ and use our combined force to make JSON:API everyone’s smart default.