Slide de apresentaçaõ feita no Symfony Live 2019. Aborda de uma forma geral os conteúdos, benefícios e componentes do API Platform.

1. API
PLATFORM

2. Hello!
Eu sou Bruno Souza!
➔ Analista de Sistemas - MRE pela empresa Datainfo
➔ Graduado em Análise e Desenvolvimento de Sistemas - UNIP
➔ Pós-graduando em Big Data e Ciência de Dados - PUC Minas
➔ ZCPE
➔ Microsoft Specialist - HTML5, CSS e JS
@Bruno_HSouza brunohsouza

3. A utilização de APIs traz algumas vantagens como:
➔ Grande oportunidade de negócios para empresas;
➔ Novos fluxos de receita
➔ Maximização de valores para os clientes e negócio
➔ Expansão de mercado
➔ Ponto central de processamento e acesso aos dados
➔ Encapsulamento da lógica de negócios
➔ Disponibilização das funcionalidades em diversos dispositivos

4. A ascensão do uso de API’s em uma abordagem técnica se torna um desafio, pois a
arquitetura deve ser:
➔ Sólida;
➔ Segura;
➔ Performática;
➔ Flexível;
➔ Auto-escalável;
➔ Resiliente;
➔ Altamente disponível

6. O que é o API Platform?
Um conjunto de ferramentas para facilitar a criação e o
consumo de Web API’s.
Segundo o conceito de plataforma em TI, pode ser definido
como: um grupo de tecnologias que são usadas como
base sobre a qual outras aplicações, processos ou
tecnologias são desenvolvidas.

7. O que é o API Platform?
Visa oferecer um conjunto de ferramentas e
padrões para facilitar a construção de sistemas
baseados em API.

8. “ API Platform is the most
advanced API platform, in
any framework or language.
Fabien Potencier

9. ➔ Desenvolvido por Kévin Dunglas
➔ Possui 4.172 estrelas no Git Hub [17 de maio de 2019
]
➔ 437 Forks no Git Hub [17 de maio de 2019]
➔ Versão 2.4.2 [17 de maio de 2019]

10. Getting Start
Instalação
10

11. A forma recomendada para a instalação do API Platform e utilização de uma forma mais
rápida é via docker-compose. Para isto, basta:
1. Baixar uma versão de sua distribuição oficial ou via git clone pelo github;
2. Instalar o Docker (caso já não tenha feito);
3. Abrir o terminal onde está o skeleton do projeto;
4. Executar os comandos:
a. docker-compose pull - para baixar a última versão da imagem
b. docker-compose up -d - para executar em background ou docker-
compose up para executar em primeira tela, permitindo visualizar os logs de
acesso e erro referentes aos containers;

12. Demo Instalação
12

14. Distribuição dos containers
Nome Descrição Porta(s)
php Onde fica a API e o seu código-fonte, composer e configs 9000 | n/a
db Um servidor de banco de dados com o PostgresSQL 5432
client Um servidor de desenvolvimento para a camada front-end (PWA, SPA) 80
admin Um servidor de desenvolvimento para gerenciamento do conteúdo do site 81
cache-proxy Um servidor HTTP de cache proxy baseado em Varnish 8081
mercure Servidor dedicado para execução do protocolo Mercure 443
h2-proxy Um servidor HTTPS e HTTP/2 com proxy para todos os apps 443 (client)
444 (admin)
8443 (api)
8444 (cache-proxy)

15. Isto é demais para
você ou o seu
projeto?

16. Instalando com Composer
16

17. Você pode fazer a instalação via Composer, utilizando a estrutura do Symfony Flex e a recipe
para o API Platform. Para isto, basta executar os seguintes passos:
➔ Execute: composer create-project symfony/skeleton my-api
➔ Entre no diretório de instalação e execute o comando: composer req api
➔ Para executar a API com o WebServerBundle: composer req server-dev
➔ Para visualização do site execute: bin/console server:run
➔ Acesse o localhost do server, geralmente http://127.0.0.1:8000;
➔ Para acessar a interface de documentação da API, acesse: http://127.0.0.1:8000/api

18. Estrutura

19. Distribuído em alguns componentes principais:
➔ The API Component;
➔ The Admin Component;
➔ The Client Component;
➔ The Schema Generator Component;

20. The Schema Generator
Component

21. O Schema Generator Component é uma ferramenta executada via linha de comando no
terminal (CLI) para facilitar e gerar modelos de dados instantâneos a partir do
vocabulário do site Schema.org;

22. O Schema.org é uma comunidade colaborativa fundada por
membros do Google, Microsoft, Yahoo e Yandex com a missão de
criar, manter e promover schemas para estruturas de dados na
internet.
Possui um vocabulário que pode ser utilizado em diversos
formatos. Este vocabulário é facilmente estendido e abordam
entidades, relacionamentos e actions.

23. Conjunto de vocábulos ou palavras representadas em uma
determinada língua
Vocabulário

25. Para utilizar o Schema Generator basta executar o comando no terminal:
docker-compose exec php vendor/bin/schema
Caso não esteja utilizando o API Platform com o docker é possível instalar o componente
via Composer executando o comando:
composer require --dev api-platform/schema-generator

26. Para executar o Schema Generator:
➔ acesse o site Schema.org, escolha os types e properties dos dados necessários para
a sua aplicação;
➔ Com os dados escolhidos, crie um arquivo chamado schema.yaml dentro do
diretório config da sua API e preencha conforme o modelo dos dados do
Schema.org;
➔ Execute o comando para gerar os modelos:
vendor/bin/schema generate-types src config/schema.yaml

27. types:
# Parent class of Person
Thing:
properties:
name: ~
Person:
properties:
familyName: ~
givenName: ~
additionalName: ~
address: ~
PostalAddress:
# Disable the generation of the class hierarchy for this type
parent: false
properties:
# Force the type of the addressCountry property to text
addressCountry: { range: "Text" }
addressLocality: ~
addressRegion: ~
postOfficeBoxNumber: ~
postalCode: ~
streetAddress: ~

29. The API Component

30. ├── bin
├── config
│ ├── packages
│ └── routes
├── docker
│ ├── nginx
│ ├── php
│ └── varnish
├── helm
│ └── api
├── public
│ └── bundles
├── src
│ ├── Controller
│ ├── Entity
│ └── Repository
├── templates
└── var

31. Considerações
➔ Code First
➔ Design First
➔ @ApiResource annotation
➔ Data Persisters
➔ Data Providers
◆ CollectionDataProviderInterface
◆ ItemDataProviderInterface
➔ Padrões (CQS, CQRS, REST, GRAPHQL, Event Sourcing)

32. Operações

33. Método Obrigatório Descrição
GET SIM Recupera uma lista de elementos (paginados)
POST NÃO Cria um novo elemento
Método Obrigatório Descrição
GET SIM Recupera um elemento
PUT NÃO Altera um elemento
DELETE NÃO Deleta um elemento
Collection
Item

34. Habilitando/Desabilitando
Operações

35. ➔ É possível habilitar ou desabilitar operações da seguinte forma:
/**
* A person (alive, dead, undead, or fictional).
* @see http://schema.org/Person Documentation on Schema.org
* @ORMEntity
* @ApiResource(iri="http://schema.org/Person"
* @collectionOperations={"create”={"method"="POST"}},
* @itemOperations={"find"={"method"="GET"}},
* )
*/
class Person
{
...
}

36. Configurando Operações

37. /**
* A person (alive, dead, undead, or fictional).
* @see http://schema.org/Person Documentation on Schema.org
* @ORMEntity
* @ApiResource(iri="http://schema.org/Person"
* @collectionOperations={"create”={"method"="POST"}},
* @itemOperations={"find"={"method"="GET", path=”/person/{id}”,
“requirements”={“id”=”d+”}, “defaults”={“color”=”brown”}, “options”={“my-
option”=”my-option-value”}, “schemes”={“https”}, “host”=”{subdomain}.api-
platform.com”, “put”=”method”=”PUT”, “path”=”/person/{id}”,
“hydra_context”={“foo”=”bar”}
},
* )
*/
class Person

38. Subresources

39. /**
* @ORMEntity
* @ApiResource(iri="http://schema.org/Person"
* subresourceOperations={
* “get_address_subresource”= {
* “method=”GET”, “path”=”/person/{id}/all-address”
* }
* },
* )
*/
class Person
{
/**
* @var PostalAddress|null physical address of the item
* @ORMManyToOne(targetEntity="AppEntityPostalAddress")
* @ApiProperty(iri="http://schema.org/address")
* @ApiSubresource(maxDepth=1)
*/
private $address;

40. {
"person": {
"@id": "/people/1",
"@type": "Person",
"additionalName": "Iron Man",
"address": {
"home": [{ ... },
"work": [{
"city": "New York",
"zipCode": "11445",
"country": "United States",
"coordinates": [{
"latitude": "-73.935242",
"longitude": "40.730610"
}]
}]
}]
},
"familyName": "Stark",
"givenName": "Tony",
"id": 1
}
}

41. Content Formats

42. Suporta alguns formatos de dados como:
○ json-ld {application/ld+json}
○ json {application/json}
○ json-hal {application/hal+json}
○ json-api {application/vnd.api+json}
○ csv {text/csv}
○ yaml {application/x-yaml}
○ xml {application/xml}
○ html {text/html}
○ my-format {application/vnd.my-format}

43. JSON-LD

44. Json-LD - Json for Linked Data
➔ É um formato de serialização utilizado na comunicação entre aplicações cliente e
servidor;
➔ Baseado na RFC4627
➔ Padronizado pela W3C recommandation (2014) para formatos de hypemedia;
➔ Fácil de usar: JSON em formato padrão, mas com algumas chaves especiais (@) e
mapeadas por contexto;
➔ Apoiado por empresas como: Google, BBC, Microsoft e órgãos governamentais de alguns
países (EUA e Europa);
➔ Compatível com tecnologias de web semântica: RDF, SPARQL, etc.

45. Json-LD Oferece
➔ Maior interoperabilidade entre os dados
➔ Mecanismo de identificação universal através de IRI’s (Internationalized Resource
Identifier)
➔ Forma de distinguir chaves compartilhadas por meio de mapeamentos através IRI’s e
contexts
➔ Mecanismo de referências entre objetos JSON
➔ Associação de tipos de dados
➔ Facilidade de expressar gráficos direcionados em um único documento

46. Json-LD (Objetivos)
➔ Simplicidade
➔ Compatibilidade
➔ Intensidade
➔ Internacionalização (@language)
➔ Expressividade

47. Linked Data Principles
➔ Usar as URI’s para nomear as coisas
➔ Use URIs HTTP para que as pessoas possam procurar o desejado
➔ Quando alguém pesquisar por URI’s, forneça informações úteis
➔ Inclua links para outras URI’s para que eles possam descobrir mais
dados
Tim Berners Lee

48. {
"@context": "https://json-ld.org/contexts/person.jsonld":
{
“@language”: "en-US"
},
"@id": "http://dbpedia.org/resource/Tony_Stark",
"name": "Tony Stark",
"born": "1940-10-09",
"spouse": "http://dbpedia.org/resource/Pepper_Potts"
}

49. Hydra

50. 54

51. ➔ É um padrão que permite uma construção mais amigável e interoperável de API’s;
➔ Sua fundação é baseada no Hydra Core Vocabulary (http://www.hydra-
cg.com/spec/latest/core/);
➔ Define alguns conceitos e fundamentos que permitem clientes entenderem como
interagir com API’s, uma vez que as informações estão disponíveis em um formato
genérico;
➔ Disponibiliza uma descoberta de entrypoints automaticamente se os cabeçalhos das
responses da API estiverem no formato estipulados pela RFC5988;
➔ Permite que os dados sejam lidos por humanos e máquinas através de markups;

52. {
"@context": "http://www.w3.org/ns/hydra/context.jsonld",
"@id": "http://api.example.com/doc/",
"@type": "ApiDocumentation",
"title": "The name of the API",
"description": "A short description of the API",
"entrypoint": "URL of the API's main entry point",
"supportedClass": [
... Classes known to be supported by the Web API ...
],
"possibleStatus": [
... Statuses that should be expected and handled properly ...
]
}

53. Segurança

54. ➔ JSON Web Token (JWT) Authentication
➔ composer req lexik/jwt-authentication-bundle
➔ Requer configuração necessária
➔ Utiliza o Symfony Security Component
➔ Suporte ao OAuth
➔ Segue as orientações da OWASP (Open Web Application Security Project)

55. /**
* Secured resource.
*
* @ApiResource(
*
attributes={"access_control"="is_granted('ROLE_USER')"},
* collectionOperations={
* "get",
*
"post"={"access_control"="is_granted('ROLE_ADMIN')"}
* },
* itemOperations={
* "get"={"access_control"="is_granted('ROLE_USER')
and object.owner == user"}
* }
* )
* @ORMEntity
*/
class Person

56. Message Bus

57. /**
* @ApiResource(
* messenger=true,
* collectionOperations={
* "post"={"status"=202}
* },
* itemOperations={},
* output=false
* )
*/
final class ResetPasswordRequest

58. Baseado em Symfony

59. "symfony/http-foundation",
"symfony/http-kernel",
"symfony/property-access",
"symfony/property-info",
"symfony/serializer",
"symfony/web-link",
"symfony/validator",
"symfony/web-profiler-bundle",
"symfony/yaml"
"symfony/asset",
"symfony/cache",
"symfony/config",
"symfony/console",
"symfony/css-selector",
"symfony/debug",
"symfony/dependency-injection,
"symfony/doctrine-bridge",
"symfony/dom-crawler",
"symfony/event-dispatcher",
"symfony/expression-language",
"symfony/finder",
"symfony/form",
"symfony/framework-
bundle",
"symfony/mercure-bundle",
"symfony/messenger",
"symfony/phpunit-bridge",
"symfony/routing",
"symfony/security",
"symfony/security-bundle",
"symfony/twig-bundle",

60. Com base no Symfony Framework, possui várias funcionalidades como:
➔ Pagination
➔ Filters
➔ Ordenação
➔ Validates
➔ Serializer
➔ Router
➔ Tratamento de erros
➔ Cache
➔ Events
➔ Messenger
➔ Suporte aos Bundles do FOS
➔ Suporte à GraphQL
➔ Segurança
➔ Data Providers;
➔ Data Persisters;
➔ HTTPKernel
➔ HTTP/2

61. Integrações

62. Oferece suporte à outras funcionalidades, como:
➔ Autenticação com JSON Web Token (JWT);
➔ Autenticação com o OAuth utilizando FosOAuthServer;
➔ Envios de e-mails com Swift Mailer;
➔ Integração com RabbitMQ;
➔ Integração com o MongoDB;
➔ Integração com o Elastic Search;
➔ Integração e utilização do protocolo Mercure;

63. Controllers

64. ➔ Qualquer Symfony Controller válida
➔ Recomenda-se utilizar o event system quando aplicável
➔ Utiliza o padrão ADR (Action-Domain-Responder)
Action
Domain Responder

65. API REST

66. ➔ Criado em 2000 por Roy Fielding em uma tese de mestrado
➔ Recursos com identificação única (URI);
➔ Uma funcionalidade por verbo HTTP;
➔ Utiliza uma interface única para requisições;
➔ Utiliza JSON como formato padrão;
➔ Stateless
➔ Hypermedia
➔ Formato de API padrão utilizado pelo API Platform

67. Documentação

68. ➔ Baseada na especificação do OpenAPI
➔ Utiliza as ferramentas Swagger e ReDoc
➔ Possui template Configurável
➔ Compatível com a camada de API Gateway da AWS
➔ Por padrão vem com o Swagger UI habilitado

70. API GraphQL

71. ➔ Query Language para API criada pelo Facebook em 2012;
➔ Fortemente tipada;
➔ Retorna apenas os dados requisitados pelo cliente;
➔ Retorna vários recursos em um único request;
➔ Baseado em 3 tipos de requisições (root types):
◆ query;
◆ mutation;
◆ subscription;
➔ docker-compose exec php composer req webonyx/graphql-
php && bin/console cache:clear

73. /**
* @ApiResource(
* attributes={
* "filters"={"people.search_filter"}
* },
* graphql={
* "query"={
* "filters"={"people.date_filter"}
* },
* "delete",
* "update",
* "create"
* }
* )
*/
class Offer
{
// ...
}

74. Documentação

75. ➔ Documentação interativa com o GraphiQL
➔ IDE no browser com várias funcionalidades como:
◆ Possibilidade de testar as querys e mutations;
◆ Prettify;
◆ Histórico;
◆ Documentação com filtro para buscas;
◆ Autocomplete;

77. The Admin Component

78. ├── Dockerfile
├── node_modules
├── package.json
├── public
│ ├── favicon.ico
│ ├── index.html
│ └── manifest.json
├── README.md
├── src
│ ├── App.js
│ ├── App.test.js
│ ├── index.js
│ └──
serviceWorker.js
└── yarn.lock

79. O API Platform Admin é um componente para suporte a criação de conteúdos da API.
➔ Possui um layout baseado em Material Design;
➔ Baseado em React;
➔ SPA sem acoplamento com o Back-end;
➔ Totalmente customizável;
➔ Gerador de CRUD para todas as resources presentes na API;
➔ Gerador de código baseado na API Doc ou no Schema.org;
➔ Suporte à paginação e autenticação;
➔ Exibição de erros amigáveis;

81. The Client Component

82. ├── Dockerfile
├── node_modules
├── package.json
├── public
│ ├── favicon.ico
│ ├── index.html
│ └── manifest.json
├── README.md
├── src
│ ├── config
│ ├── index.js
│ ├──
serviceWorker.js
│ ├── welcome.css
│ └── Welcome.js
└── yarn.lock

83. The Client Component
O Client Generator é o caminho mais rápido para criação de webapps e apps mobile
➔ Suporta o formato de dados Hydra;
➔ Suporta React, React Native, Vue.js e Angular;
➔ Integração com Bootstrap e Font Awesome;
➔ Utiliza conceitos do ES6;
➔ Utilização de input types apropriados;
➔ Suporte a atualizações utilizando o protocolo Mercure;
➔ Suporte à pessoas com deficiência (ARIA);

84. Conclusão

85. ➔ API Platform é um conjunto com as principais tendências em ferramentas no
mercado para construção de API’s de uma forma mais fácil e rápida
➔ Possui uma filosofia de não prender o desenvolvedor em estruturas já criadas,
grandes possibilidades de customização para se adequar às especificações dos
projetos
➔ Possui uma filosofia de melhorar a forma de como se desenvolve API’s
oferecendo as melhores práticas

86. Agradecimentos