Criando API's em um passo com o API Platform

Slide 1

Slide 1 text

API PLATFORM

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

A utilização de APIs traz algumas vantagens como: ➔ Grande oportunidade de negócios para empresas; ➔ Novos ﬂuxos 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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

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 deﬁnido como: um grupo de tecnologias que são usadas como base sobre a qual outras aplicações, processos ou tecnologias são desenvolvidas.

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Getting Start Instalação 10

Slide 11

Slide 11 text

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 oﬁcial 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;

Slide 12

Slide 12 text

Demo Instalação 12

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

Distribuição dos containers Nome Descrição Porta(s) php Onde ﬁca a API e o seu código-fonte, composer e conﬁgs 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)

Slide 15

Slide 15 text

Isto é demais para você ou o seu projeto?

Slide 16

Slide 16 text

Instalando com Composer 16

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

Estrutura

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

The Schema Generator Component

Slide 21

Slide 21 text

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;

Slide 22

Slide 22 text

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.

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

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 conﬁg 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

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

The API Component

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

Operações

Slide 33

Slide 33 text

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

Slide 34

Slide 34 text

Habilitando/Desabilitando Operações

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

Conﬁgurando Operações

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

Subresources

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

Content Formats

Slide 42

Slide 42 text

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}

Slide 43

Slide 43 text

JSON-API

Slide 44

Slide 44 text

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;

Slide 45

Slide 45 text

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;

Slide 46

Slide 46 text

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

Slide 47

Slide 47 text

JSON-LD

Slide 48

Slide 48 text

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.

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

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

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

Hydra

Slide 54

Slide 54 text

Slide 55

Slide 55 text

➔ É 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/); ➔ Deﬁne 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;

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

Segurança

Slide 58

Slide 58 text

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

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

Message Bus

Slide 61

Slide 61 text

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

Slide 62

Slide 62 text

Baseado em Symfony

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

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

Slide 65

Slide 65 text

Integrações

Slide 66

Slide 66 text

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;

Slide 67

Slide 67 text

Controllers

Slide 68

Slide 68 text

➔ 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

Slide 69

Slide 69 text

API REST

Slide 70

Slide 70 text

➔ Criado em 2000 por Roy Fielding em uma tese de mestrado ➔ Recursos com identiﬁcaçã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

Slide 71

Slide 71 text

Documentação

Slide 72

Slide 72 text

➔ Baseada na especiﬁcação do OpenAPI ➔ Utiliza as ferramentas Swagger e ReDoc ➔ Possui template Conﬁgurável ➔ Compatível com a camada de API Gateway da AWS ➔ Por padrão vem com o Swagger UI habilitado

Slide 73

Slide 73 text

No content

Slide 74

Slide 74 text

API GraphQL

Slide 75

Slide 75 text

➔ 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

Slide 76

Slide 76 text

No content

Slide 77

Slide 77 text

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

Slide 78

Slide 78 text

Documentação

Slide 79

Slide 79 text

➔ 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 ﬁltro para buscas; ◆ Autocomplete;

Slide 80

Slide 80 text

No content

Slide 81

Slide 81 text

The Admin Component

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

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;

Slide 84

Slide 84 text

No content

Slide 85

Slide 85 text

The Client Component

Slide 86

Slide 86 text

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

Slide 87

Slide 87 text

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 deﬁciência (ARIA);

Slide 88

Slide 88 text

Conclusão

Slide 89

Slide 89 text

➔ 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