Share
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
BRUNO SOUZA
Transcript
91 slides
-
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) -
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; -
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. -
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 -
➔ É 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 { ... } -
/** * 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 -
/** * @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; -
{ "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-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; -
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; -
{ "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" } } } } } -
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"} * } * ) * @ORM\Entity */ 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