Symfony Live - São Paulo 2019 - Como construir uma API em um passo com API Platform

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

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

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

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.

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

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

➔ 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]

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;

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)

Isto é demais para você ou o seu projeto?

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

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

The Schema Generator Component

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;

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.

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

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

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

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: ~

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

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

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

Habilitando/Desabilitando Operações

➔ É 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 { ... }

/** * 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

/** * @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;

{ "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 } }

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}

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.

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

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

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

{ "@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" }

➔ É 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;

{ "@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 ... ] }

➔ 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)

/** * 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

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

"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",

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

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;

➔ 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

➔ 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

➔ 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

➔ 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

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

➔ 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;

├── 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

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;

├── 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

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);

➔ 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

Symfony Live - São Paulo 2019 - Como construir uma API em um passo com API Platform

Symfony Live - São Paulo 2019 - Como construir uma API em um passo com API Platform

Mais conteúdo relacionado

Mais procurados

Semelhante a Symfony Live - São Paulo 2019 - Como construir uma API em um passo com API Platform

Symfony Live - São Paulo 2019 - Como construir uma API em um passo com API Platform

Notas do Editor