Criando API's em um passo com o API Platform

O API Platform é um framework dedicado para facilitar a construção de projetos baseados em API's REST ou GraphQL.

Esta plataforma criada com o Symfony como base, contém diversos módulos acoplados que tornam as integrações com as tecnologias e padrões que são últimas tendências de mercado mais fáceis.

Dentre as vantagens de usar o API Platform podemos destacar:

Segurança. Segue os padrões de boas-práticas da OWASP;

Fácil integração com JWT ou OAuth para autenticação;

Gerador de documentação de API com o Swagger;

Gerador de apps PWA e Mobile para consumo da API;

Gerador de interface administrativa baseada em React;

Fácil integração com testes;

Fácil integração com o Docker;

Ganhe qualidade e agilidade em suas aplicações, do momento da criação ao deploy com o API Platform

Transcript

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 * @ORM\Entity * @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 * @ORM\Entity * @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. /** * @ORM\Entity * @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 * @ORM\ManyToOne(targetEntity="App\Entity\PostalAddress") * @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-API
44. JSON-API ➔ Uma especificação que visa padronizar a forma como os clientes devem fazer requisições para consultas ou modificações das resources e como o servidor deve responder à estes requests. ➔ Foi idealizado para minimizar a quantidade de requests e de dados transmitidos entre cliente e servidor. ➔ Sua eficiência é garantida sem comprometer a legibilidade, flexibilidade ou cobertura dos dados;
45. JSON-API (Especificações) ➔ Os clientes devem sempre submeter suas requests com o Header contendo: Content-Type: application/vnd.api+json ➔ Clientes devem especificar o tipo do media type caso implementem o tipo JSON-API no campo Accept do header; ➔ Um objeto JSON deve estar na raiz de toda transação com API contendo dados, definindo um “documento”; ➔ Um documento deve conter no mínimo um dos membros: data, errors, meta; ➔ A chave “data” é a representação de uma resource ou resource collection;
46. { "data": { "type": "persons", "id": "1", "attributes": { "name": "Peter Parker" }, "relationships": { "team": { "links": { "self": "/avengers/1/relationships/ironman", "related": "/avengers/1/civilwar" }, "data": { "type": "people", "id": "9" } } } } }
47. JSON-LD
48. 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.
49. 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
50. Json-LD (Objetivos) ➔ Simplicidade ➔ Compatibilidade ➔ Intensidade ➔ Internacionalização (@language) ➔ Expressividade
51. 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
52. { "@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" }
53. Hydra
55. ➔ É 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;
56. { "@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 ... ] }
57. Segurança
58. ➔ 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)
59. /** * 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"} * } * ) * @ORM\Entity */ class Person
60. Message Bus
61. /** * @ApiResource( * messenger=true, * collectionOperations={ * "post"={"status"=202} * }, * itemOperations={}, * output=false * ) */ final class ResetPasswordRequest
62. Baseado em Symfony
63. "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",
64. 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
65. Integrações
66. 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;
67. Controllers
68. ➔ 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
69. API REST
70. ➔ 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
71. Documentação
72. ➔ 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
74. API GraphQL
75. ➔ 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
77. /** * @ApiResource( * attributes={ * "filters"={"people.search_filter"} * }, * graphql={ * "query"={ * "filters"={"people.date_filter"} * }, * "delete", * "update", * "create" * } * ) */ class Offer { // ... }
78. Documentação
79. ➔ 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;
81. The Admin Component
82. ├── 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
83. 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;
85. The Client Component
86. ├── 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
87. 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);
88. Conclusão
89. ➔ 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
90. Agradecimentos