Apresentação ministrada no Darkmira Tour PHP 2017, no dia 26/05/2017. Aberto para a comunidade em 2015, o GraphQL surgiu como uma alternativa poderosa, eficiente e bem documentada para construção de API’s. Foi desenvolvida e utilizada pelo Facebook por mais de 3 anos antes de sua publicação. Nessa conversa abordaremos os fundamentos da especificação, as principais diferenças com o REST e como desenvolver uma API GraphQL utilizando PHP.

1. Do REST ao GraphQL
com PHP
Bruno Neves
@brunodasneves
brunonm@gmail.com

2. Roteiro
★ REST & GraphQL
★ História
★ Especificação / Linguagem
★ PHP

3. App Newsfeed

4. GET /news/1
{
"id": "1",
"user_id": "57",
"media_id": "20",
"title": "Joesley rompe com Tony Ramos",
"excerpt": "Mussum, Ipsum, cacilds",
"text": "Mussum, Ipsum, cacilds vidis litro abertis...",
"created_at": "1495928417",
"status": "PUBLISHED"
}

5. GET /users/57
{
"id": "57",
"name": "Mad Max",
"email": "madmax@darkmira.com",
"role": "WRITER",
"created_at": "1495928417"
}

6. GET /medias/20
{
"id": "20",
"type": "image/jpeg",
"filename": "friboi.jpg",
"size": "204800",
"url": "http://news/media/65815736d29cc094a2d784c338066029"
}

7. GET /news/1/comments
[
{
"id": "25",
"news_id": "1",
"text": "Não sou faixa preta cumpadi, sou preto inteiris.",
"created_at": "1495928417",
"author": {
"name": "Nissim Ourfali",
"email": "nissimourfali@darkmira.com"
}
}, //... a lot of comments
]

8. /news/1
/users/57
//...
/medias/20
/news/1/comments

9. Como seria pedir
SOMENTE
o necessário e receber
EXATAMENTE
o que pediu de
UMA SÓ VEZ?

10. {
news(id: 1) {
title, text, created_at,
media {
url
},
user {
name
},
comments {
text,
author {
name
}
}
}
}

11. {
news(id: 1) {
title, text, created_at,
media {
url
},
user {
name
},
comments {
text,
author {
name
}
}
}
}
[
{
"title": "Joesley rompe com Tony Ramos",
"text": "Mussum, Ipsum, cacilds vidis...",
"created_at": "1495928417",
"media": {
"url":"http://news/media/65815736...
},
"user": {
"name": "Mad Max"
},
"comments": [
//...
]
}
]

13. História
Fevereiro 2012
Protótipo SuperGraph

14. História
Desenvolvimento inicial

15. História
Facebook Newsfeed API para iOS
Agosto 2012

16. História
Evolução

17. História
Primeira aparição pública
Janeiro 2015

18. História
Refactoring

19. História
Open Source
Julho 2015

20. História
Feedback da comunidade

21. História
Release
Setembro 2016

22. GraphQL.org

23. $ composer require webonyx/graphql-php
http://webonyx.github.io/graphql-php/

24. Schema

25. Descreve os dados

26. Cardápio

27. $userType = new ObjectType([
'name' => 'User',
'fields' => [
'id' => Type::nonNull(Type::id()),
'name' => Type::nonNull(Type::string()),
'email' => Type::nonNull(Type::string()),
'role' => Type::nonNull(Type::string()),
'created_at' => Type::nonNull(Type::int())
]
]);

28. $mediaType = new ObjectType([
'name' => 'Media',
'fields' => [
'id' => Type::nonNull(Type::id()),
'type' => Type::nonNull(Type::string()),
'filename' => Type::nonNull(Type::string()),
'size' => Type::nonNull(Type::string()),
'url' => Type::nonNull(Type::string())
]
]);

29. $commentType = new ObjectType([
'name' => 'Comment',
'fields' => [
'id' => Type::nonNull(Type::id()),
'text' => Type::nonNull(Type::string()),
'created_at' => Type::nonNull(Type::int()),
'author' => Type::nonNull(new ObjectType([
'name' => 'Author',
'fields' => [
'name' => Type::string(),
'email' => Type::string()
]
]))
]
]);

30. $newsType = new ObjectType([
'name' => 'News',
'fields' => [
'id' => Type::nonNull(Type::id()),
'user' => Type::nonNull($userType),
'media' => $mediaType,
'title' => Type::nonNull(Type::string()),
'excerpt' => Type::string(),
'text' => Type::nonNull(Type::string()),
'created_at' => Type::nonNull(Type::int()),
'status' => Type::nonNull(Type::string()),
'comments' => Type::listOf($commentType)
]
]);

31. Type System

32. Um serviço
GraphQL
é composto por
TYPES,
que por sua vez são
compostos por
FIELDS

33. Types
★ Int
★ Float
★ Boolean
★ String
★ ID
★ Object

34. Modificadores
★ List
★ Non-Null

35. Root Types

36. São tipos especiais de
objetos que ficam na raiz
do schema

37. Enquanto a MUTATION
é opcional, a QUERY
deve estar presente em
todo schema GraphQL

38. $mutationType = new ObjectType([
'name' => 'Mutation',
'fields' => [
'registerUser' => $registerUserMutation,
'registerComment' => $registerCommentMutation,
'reportContent' => $reportContentMutation
]
]);
$queryType = new ObjectType([
'name' => 'Query',
'fields' => [
'news' => $newsQuery,
'categories' => $categoriesQuery,
'users' => $usersQuery
],
]);

39. $schema = new Schema([
'query' => $queryType,
'mutation' => $mutationType
]);

40. Queries & Mutations

41. query{
news(id: 1) {
title, text, created_at,
media {
url
},
user {
name
},
comments {
text,
author {
name
}
}
}
}
$newsQuery = [
'type' => Type::listOf($newsType),
'args' => [
'id' => Type::id()
],
'resolve' => function ($root, $args) {
$id = $args['id'];
return NewsRepository::find($id);
}
];

42. MUTATION
são operações que
modificam os dados no
serviço

43. Nomenclatura imperativa

44. $registerUserMutation = [
'type' => $userType,
'args' => [
'name' => Type::nonNull(Type::string()),
'email' => Type::nonNull(Type::string()),
],
'resolve' => function ($root, $args) {
return NewsRepository::add($args);
}
];
mutation{
registerUser(
name: "Cyrille",
email: "cyrille@darkmira.com"
) {
id,
name,
email,
role,
created_at
}
}

45. Validação

46. Todo dado que entra
e sai do serviço GraphQL é
validado no
SCHEMA

47. mutation{
registerUser(name: 1) {
undefined_field
}
}
{
"errors": [
{
"message": "Argument "name" has invalid value 1.nExpected
type "String", found 1.",
"locations": [
{
"line": 2,
"column": 22
}
]
},
{
"message": "Cannot query field "undefined_field" on type
"User".",
"locations": [
{
"line": 3,
"column": 5
}
]
}
]
}

48. Resolvers

49. São os responsáveis por
resolver a QUERY, ou
MIGRATION, e retornar as
informações

50. Todo FIELD possui um
RESOLVER, mesmo
que de forma
implícita

51. O RESOLVER de um FIELD
filho recebe o resultado
do FIELD pai como
argumento

52. $newsQuery = [
'type' => Type::listOf($newsType),
'args' => [
'id' => Type::id()
],
'resolve' => function ($root, $args) {
$id = $args['id'];
return NewsRepository::find($id);
}
];

53. $newsType = new ObjectType([
'name' => 'News',
'fields' => [
'id' => Type::nonNull(Type::id()),
'user' => Type::nonNull($userType),
'media' => $mediaType,
'title' => Type::nonNull(Type::string()),
'excerpt' => [
'type' => Type::nonNull(Type::string()),
'resolve' => function ($news, $args) {
return 'Excerpt from: ' . $news->title;
}
],
'text' => Type::nonNull(Type::string()),
'created_at' => Type::nonNull(Type::int()),
'status' => Type::nonNull(Type::string()),
'comments' => Type::listOf($commentType )
]
]);

54. query {
news(id:1) {
id
title
excerpt
}
}
{
"data": {
"news": [
{
"id": "1",
"title": "Joesley rompe com ..." ,
"excerpt": "Excerpt from: Joesley
rompe com Tony Ramos"
}
]
}
}

55. Adeus versionamento
http://darkmira.com/api/v1

56. Quando um FIELD for
depreciado, é sinalizada a
mudança no SCHEMA e
definido o substituto

57. Endpoint único

58. CLIENT first

59. Entrega mais poder de
fogo para o frontend

60. Cada cliente consome o
serviço de acordo com a
sua necessidade, de
maneira eficiente. PC,
Mobile, Integrações...

61. Documentação

62. Documentação
Introspecção

63. Todo serviço
GraphQl
provê a navegação
por todo o
SCHEMA

64. A API já nasce documentada

65. {
__type(name: "News") {
name
fields {
name
}
}
}
{
"data": {
"__type": {
"name": "News",
"fields": [
{ "name": "id" },
{ "name": "user" },
{ "name": "media" },
{ "name": "title" }
//...
]
}
}
}

66. Experiência de
desenvolvimento
superior

67. Adoção

68. http://graphql.org/users

69. Frontend

70. Frontend
★ Relay
★ Apollo
★ Vanilla Js

71. Talk is cheap.
Show me the code!

72. Dúvidas?

73. Valeu!
https://joind.in/event/darkmira-tour-php-2017/do-rest-ao-graphql-com-php
@brunodasneves

74. Referências
★ http://graphql.org/
★ https://www.youtube.com/watch?v=zVNrqo9XGOs
★ https://github.com/chentsulin/awesome-graphql
★ http://webonyx.github.io/graphql-php
★ https://github.com/Youshido/GraphQL
★ https://dev-blog.apollodata.com/