Getting to JSON:API: What it is, why you should use it, and how to use it in Laravel

HOW TO JSON:API
QUICKLY & EASILY
IN LARAVEL
Getting to JSON:API - Matt Stauffer

View Slide

You can't.
THE END

View Slide

GETTING TO JSON:API
WHAT IT IS, WHY YOU SHOULD USE IT, and
HOW TO USE IT IN LARAVEL

View Slide

First half: Theory
▸ 1. Intro to REST APIs
▸ 2. The State of APIs
▸ 3. What is JSON:API?
▸ 4. Why JSON:API?

View Slide

Second half: Implementation
▸ 5. JSON:API Tooling in Laravel
▸ 6. Other API concerns
▸ 7. After the talk
▸ 8. Outro

View Slide

PART 1
Intro to
REST APIS

View Slide

REST: CRUD over JSON using HTTP verbs

View Slide

REST: CRUD over JSON using HTTP verbs
shaped like /dogs/14 and stuff

View Slide

What's "REST", anyway?

View Slide

REPRESENTATIONAL
STATE
TRANSFER

View Slide

ROY FIELDING

View Slide

REST is:
▸ Client/server
▸ Stateless
▸ Cacheable
▸ Layered (proxyable, load balanceable)
▸ Uniform Interface:
▸ Resource identification in requests
▸ Resource manipulation through representations
▸ Self-descriptive messages (content headers)
▸ Hypermedia as the Engine of Application State

View Slide

REST misconceptions:
▸ REST has no preferred URL patterns
▸ REST needn't be JSON
▸ Most REST-ish APIs aren't actually RESTful, but that's fine

View Slide

What's "HATEOAS"?

View Slide

What's "HATEOAS"?
HYPERMEDIA AS THE ENGINE
OF APPLICATION STATE

View Slide

What's "HYPERMEDIA"?

View Slide

AN EXAMPLE OF EMBEDDED HYPERMEDIA
/* GET /departments/10 */
{
"type": "departments",
"id": "10",
"attributes": {
"name": "Information Technology"
}
}

View Slide

AN EXAMPLE OF EMBEDDED HYPERMEDIA
/* GET /departments/10 */
{
"type": "departments",
"id": "10",
"attributes": {
"name": "Information Technology"
},
"links": [
{
"href": "departments/10/employees",
"rel": "employees",
"type" : "GET"
}
]
}

View Slide

APIS AS STATE MACHINES

View Slide

SHOULD WE AIM FOR TRUE HATEOAS?

View Slide

"Hard coding URIs in your documentation and thus also in all of the
clients of your API, is a clear violation of the REST constraint that
hypermedia must be the engine of application state."
- Asbjørn Ulsberg

View Slide

SHOULD WE AIM FOR TRUE HATEOAS?
PROBABLY NOT.

View Slide


View Slide

GRADUAL ADOPTION.

View Slide

PART 2
THE STATE OF APIS

View Slide

WE'RE IN THE BAD OLD DAYS
WHEN IT COMES TO API STANDARDIZATION

View Slide


View Slide

“Every sufficiently advanced API contains an ad hoc, informally-
specified implementation of some media type on top of JSON.”
- Steve Klabnik

View Slide

APIS ARE A
BIKESHEDDER'S PARADISE

View Slide

BIKESHEDDING
Wasting time and energy
on marginal technical issues.

View Slide

STOP WASTING TIME
BIKESHEDDING ON API STANDARDS

View Slide

PART 3
WHAT IS JSON:API?

View Slide

A LITTLE HISTORY:
Ember ❤ Rails

View Slide

IT'S A STANDARD

View Slide


View Slide

YOU MAY BE FAMILIAR...
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
// ... this article's attributes
},
"relationships": {
// ... this article's relationships
}
}
}

View Slide

BUT WHAT ABOUT...
▸ Compound documents in flat included key
▸ Content negotiation requirements
▸ Custom error syntax
▸ Nested include directives
▸ Sparse fieldsets
▸ Create/update/delete validation
▸ Relationship modification endpoints

View Slide

!

View Slide

THE BIG PIECES OF JSON:API

View Slide

THE BIG PIECES OF JSON:API
▸ Document structure
▸ HTTP standards

View Slide

THE BIG PIECES PART 1:
DOCUMENT STRUCTURE

View Slide

DOCUMENT STRUCTURE IN JSON:API
▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

{
"jsonapi": {
"version": "1.0"
},
"meta": {
"i can do anything": {
"i want": ["in", "here"]
}
}
}

View Slide

▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

{
"data": {
"type": "articles",
"id": "1",
}
}

View Slide

{
"data": [{
"type": "articles",
"id": "1"
},{
"type": "articles",
"id": "42"
}]
}

View Slide

THE STRUCTURE OF A
RESOURCE OBJECT

View Slide

Resource identifier object
{
"type": "articles",
"id": "1"
}

View Slide

Optional sections
{
"type": "articles",
"id": "1",
"attributes": {
// key/value pairs of all attributes
},
"relationships": {
// relationship objects
},
"links": {
// link objects
},
"meta": {
// key/value pairs
}
}

View Slide

Attributes
{
"type": "articles",
"id": "1",
"attributes": {
"title": "The greatest post ever",
"body": "Lorem ipsum"
},
}

View Slide

Relationships
{
"type": "articles",
"id": "1",
"relationships": {
"author": {
"data": {
"type": "people",
"id": "5"
}
}
}
}

View Slide

▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

COMPOUND DOCUMENTS
{
"data": {
"type": "articles", "id": "123", "attributes": {},
"relationships": {
"author": { "data": { "type": "people", "id": "5" }}
}
},
"included": [{
"type": "people",
"id": "5",
"attributes": {
"name": "Phil the GOAT"
}
}]
}

View Slide

▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

LINKS
{
"data": [{}, {}, {}],
"links": {
"self": "http://site.com/articles?page=3",
"first": "http://site.com/articles?page=1",
"prev": "http://site.com/articles?page=2",
"next": "http://site.com/articles?page=4",
"last": "http://site.com/articles?page=42"
}
}

View Slide

▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

ERRORS
{
"errors": [{
"id": "SERVER500C1",
"links": {},
"status": "500",
"code": "SERVER500C1",
"title": "A server error has occurred.",
"detail": "Longer message here.",
"source": { /* Object containing references to the source */},
"meta": {}
}]
}

View Slide

ERRORS
{
"errors": [{
"status": "500",
"title": "A server error has occurred."
}]
}

View Slide

▸ data
▸ included
▸ links
▸ errors
▸ meta
▸ jsonapi

View Slide

THE BIG PIECES PART 2:
HTTP SPECS

View Slide

HTTP SPECS IN JSON:API
▸ Content Negotiation
▸ Verbs & Status Codes
▸ Query parameters (include, page, sort, filter, fields)

View Slide

CONTENT NEGOTIATION

View Slide

VERBS & STATUS CODES
Use them. The way they were meant to be used.
Note: If a JSON:API feature is requested and you don't support it (e.g. ?
include), return a 400 BAD REQUEST

View Slide

QUERY PARAMETERS
▸ OPINIONATED:
▸ ?include=author,comments.author
▸ ?sort=created_at,-name
▸ ?fields[articles]=title,body&fields[people]=name
▸ UNOPINIONATED:
▸ ?page=5
▸ ?filter[abc]=def

View Slide

Important note:
You don't have to fully adhere to a standard to learn from it.

View Slide

PART 4
WHY JSON:API?

View Slide

WHY NOT OPENAPI?

View Slide

WHY NOT GRAPHQL?

View Slide

JSON:API: "A speciﬁcation for Fetching
and Mutating a Graph of Data"
— Dan Gebhardt

View Slide

WHY NOT HAL, SIREN, JSON-LD,
COLLECTION+JSON?

View Slide

WHY NOT HTTP/2?

View Slide

However...

View Slide


View Slide

SO, WHY JSON:API?
Stealing from Dan Gebhardt, co-editor of JSON:API:

View Slide


View Slide

PART 5
JSON:API TOOLING
IN LARAVEL

View Slide

Which t l
should I pick?

View Slide

https://github.com/tightenco/json-api-examples
*Totally incomplete examples!

View Slide

Intro to
ELOQUENT RESOURCES
FOR JSON API

View Slide

class ArticleResource
{
public function toArray()
{
return [
'data' => [
'type' => 'articles',
'id' => $this->resource->id,
],
'attributes' => [
'title' => $this->resource->title,
],
];
}
}

View Slide

class ArticleController
{
public function index()
{
$articles = QueryBuilder::for(Article::class)
->allowedIncludes(['author', 'comments'])
->allowedSorts(['created_at', 'title'])
->paginate();
return new ArticleCollection($articles);
}
}

View Slide


View Slide

!

View Slide

CONCLUSION
Good for simple applications,
but lots of work for full implementation.
With Spatie Query Builder, you can get far.
But no flat included.

View Slide


View Slide

HOW DO I USE IT?
https://github.com/tightenco/json-api-examples/tree/eloquent-
resources

View Slide

Intro to
FRACTAL FOR JSON API

View Slide

public function index()
{
$articles = QueryBuilder::for(Article::class)
->allowedIncludes(['author', 'comments'])
->allowedSorts(['created_at', 'title'])
->paginate(5);
return fractal($articles, new ArticleTransformer)
->withResourceName('articles')
->respondJsonApi();
}

View Slide

class AuthorTransformer extends TransformerAbstract
{
protected $defaultIncludes = [];
protected $availableIncludes = ['articles'];
public function transform(User $user)
{
return [
'id' => (int) $user->id,
'name' => $user->name,
];
}
public function includeArticles(User $user)
{
return $this->collection($user->articles, new ArticleTransformer, 'articles');
}
}

View Slide

CONCLUSION
Great for serializing even complex use cases,
and great if you're a Fractal fan,
but there's still manual work to be done.
Also requires Spatie Query Builder to get far.
Includes flat included for free.

View Slide


View Slide

HOW DO I USE IT?
https://github.com/tightenco/json-api-examples/tree/fractal

View Slide

Intro to
LARAVEL-JSON-API
FOR JSON API

View Slide

class Schema extends SchemaProvider
{
protected $resourceType = 'articles';
public function getId($resource)
{
return (string) $resource->getRouteKey();
}
public function getAttributes($resource)
{
return [
'title' => $resource->title,
'body' => $resource->body,
];
}
public function getRelationships($resource, $isPrimary, array $includedRelationships)
{
return [
'author' => [
self::SHOW_SELF => true,
self::SHOW_RELATED => true,
self::SHOW_DATA => isset($includedRelationships['author']),
self::DATA => function () use ($resource) {
return $resource->author;
},

View Slide

class Adapter extends AbstractAdapter
{
protected $attributes = [];
protected $filterScopes = [];
protected function author()
{
return $this->belongsTo('user');
}
protected function comments()
{
return $this->hasMany();
}
}

View Slide

CONCLUSION
Steep learning curve,
but the best way to get
even close to full JSON:API.

View Slide


View Slide

HOW DO I USE IT?
https://howtojsonapi.com/laravel.html

View Slide

PART 6
OTHER API CONCERNS

View Slide

AUTH
▸ Airlock
▸ Passport
▸ Simple token

View Slide

CACHING
▸ Cache DB requests
▸ Full HTTP request caching
▸ Intermediary caching (Varnish, Cloudflare)

View Slide

PART 7
AFTER THE TALK

View Slide

▸ Relationship endpoints
▸ True HATEOAS
▸ Etags & cache-control/expires
▸ JSON Schema for defining types (client-side validation!)
▸ HTTP/2 Server Push
▸ JSON:API 1.1

View Slide

PART 8
OUTRO

View Slide

TL;DR
▸ API standards are great
▸ JSON:API is a great standard
▸ Gradual adoption means there are no judgments!
▸ If you don't adopt something, error if it's asked for
▸ Eloquent Resources/Fractal + Spatie Query Builder for JSON:API lite,
Laravel-JSON-API for full spec

View Slide

RESOURCES
Slides, links, and lists at:
https://mattstauffer.com/json-api

View Slide

Getting to JSON:API: What it is, why you should use it, and how to use it in Laravel

Getting to JSON:API: What it is, why you should use it, and how to use it in Laravel

Matt Stauffer

More Decks by Matt Stauffer

Other Decks in Technology

Featured

Transcript