Instrutor: Eder Martins Franco

Transcrição

1 Minicurso de REST Aula 1 fsdfsdf Introdução às RESTful APIs com PHP Instrutor: Eder Martins Franco 27 MAI 2017 Faculdade FUCAPI v1.0

2 Professor who? Programador e professor, notívago e viciado em café. Cristão, nerd, gamer e amigo da vizinhança Introdução às RESTFul APIs com PHP - Aula 1

3 Agenda Introdução Por que utilizar REST? Webservices tradicionais x REST O que é REST? Protocolo HTTP e REST Boas práticas de uso do HTTP; O que é uma API? Fundamentos do HTTP; Conceitos de REST; JSON e XML; Arquitetura; #comofaz? Implementação em PHP 3 3 Referências Introdução às RESTFul APIs com PHP - Aula 1

4 Ninguém é tão sábio que não tenha algo pra aprender e nem tão tolo que não tenha algo pra ensinar Blaise Pascal

5 5 Introdução

6 Introdução Arquitetura cliente-servidor 6 6

7 7 O problema do Sr. Gustavo

8 8 Vamos criar um webservice!

9 Introdução Arquitetura utilizando um webservice A API pode ser acessada por qualquer tipo de cliente: Uma aplicação web em um browser; Um aplicativo nativo para smartphone (Android, IOS, Windows); Uma aplicação desktop ou outro sistema/api; 9 9

10 Por que utilizar REST? Webservices tradicionais são complicados de implementar; Exemplo: SOAP (simple object access protocol); Um protocolo para troca de informações estruturadas, baseada na linguagem XML; No SOAP, o XML é uma vantagem e desvantagem; + Boa estruturação dos dados; + Metadados; - Parse mais complexo; - Manipulação não é tão simples; 10 10

11 11 E agora?

12 Por que utilizar REST? REST Representational State Transfer (transfererência de estado representativo); Roy Fielding (2000): Coautor do HTTP; Tese de Doutorado; REST baseasse no protocolo HTTP e é guiado pelos seus princípios; HTTP (protocolo de transferência de hipertexto); 12 12

13 Boas práticas de uso do HTTP: Uso adequado dos métodos HTTP; Uso adequado de URLs; Uso de códigos de status padronizados para representação de sucessos ou falhas; Uso adequado de cabeçalhos HTTP; Interligações entre vários recursos diferentes. O padrão REST utiliza-se do HTTP para implementar APIs acessíveis pela web; 13 13

14 (PARÊNTESIS): E você sabe o que é uma API? Application Programming Interface; Conjunto de rotinas, padrões, especificações, protocolos e ferramentas para acesso ou construção de uma aplicação; Permitem a comunicação entre aplicações (não necessariamente web); 14 14

15 (PARÊNTESIS): Exemplos de APIs: API do Windows (antiga) : Win32 API ou simples Windows API; APIs do Android: Atualmente Android N (API level 25); Contida no Android SDK Exemplos de APIs web: Marvel Comics; Spotify; Facebook; 15 15

16 Conceitos importantes para o REST: Recurso: São o conjunto de dados que será trafegado pelo protocolo; São representados por URLs; Na documentação de algumas APIs, as URLs de acesso a um recurso também são comumente chamadas de endpoints. Exemplos URLs públicas da API do ENCOSIS:

17 Conceitos importantes para o REST: Exemplo: Detalhamento: - Indica o protocolo; encosis.com.br Indica o servidor (e a porta, se necessário); /api/public/ paths da api; v2/ - versão; inscricao/ - contexto da aplicação ou apenas contexto; tipo endereço do recurso; 17 17

18 Conceitos importantes para o REST: Protocolo: Escolhido pelo autor da especificação (já que ele era coautor do protocolo); HTTP é o único 100% compatível com a especificação; HTTPS (possui uma camada extra de segurança sobre o HTTP); 18 18

19 Fundamentos do HTTP: Permite realizar e receber requisições de um servidor web; Formato geral da requisição: Quando acessamos a URL anterior, algo semelhante a isso foi enviado: 19 19

20 Fundamentos do HTTP: Formato geral da resposta: DICA: Você pode inspecionar as requisições feitas pelo seu navegador nas ferramentas de desenvolvedor (geralmente apertando F12), na seção network (rede) 20 20

21 Fundamentos do HTTP: Métodos: HTTP 1.1 define oficialmente 9 métodos: GET POST PUT DELETE OPTIONS HEAD TRACE CONNECT PATCH Cada método é utilizado de acordo com uma necessidade

22 Fundamentos do HTTP: Métodos: HTTP 1.1 define oficialmente 9 métodos: GET POST PUT Mais utilizados com REST DELETE OPTIONS HEAD TRACE CONNECT PATCH Cada método é utilizado de acordo com uma necessidade

23 Fundamentos do HTTP: Cabeçalhos: Contém metadados sobre as requisições; Exemplo: Ao acessar

24 Fundamentos do HTTP: Códigos de status: Toda requisição retorna um código de status; São divididos em cinco grupos: 1xx Informacionais; 2xx Códigos desucesso; 3xx Códigos de redirecionamento; 4xx Erros causados pelo cliente; 5xx Erros originados no servidor

25 Fundamentos do HTTP: Códigos de status: Mais utilizados: 200 A requisição realizada obteve sucesso; 301 Movido permanentemente O recurso solicitado foi realocado permanentemente para outra URL, e acompanha um cabeçalho location com a descrição do protocolo e servidor da nova localização do recurso; 307 Mesmo significado do 301, mas com redirecionamento temporário; 400 Requisição mal formada (resposta genérica de erros); 403 Método não autorizado; 404 Recurso não encontrado; 500 Erro interno do servidor (erro genérico, usado quando nenhum outro se aplica); 25 25

26 Fundamentos do HTTP: Códigos de status: Mais utilizados: 200 A requisição realizada obteve sucesso; 301 Movido permanentemente O recurso solicitado foi realocado permanentemente para outra URL, e acompanha um cabeçalho location com a descrição do protocolo e servidor da nova localização do recurso; 307 Mesmo significado do 301, mas com redirecionamento temporário; 400 Requisição mal formada (resposta genérica de erros); 403 Método não autorizado; 404 Recurso não encontrado; 500 Erro interno do servidor (erro genérico, usado quando nenhum outro se aplica); 26 26

27 Conceitos de REST REST baseia-se nos conceitos do HTTP, mas possui algumas regras; Uma API que utiliza o padrão REST é chamada RESTFul; As principais regras são: Semântica de recursos; Interação por métodos; Representações distintas; Uso correto dos códigos de status; 27 27

28 Conceitos de REST Semântica de Recursos As URLs que representam um recurso devem ser significativas, descrevendo-o de maneira objetiva; Exemplo: Se eu quero criar um recurso para listar minicursos, uma boa representação para reste recurso seria:

29 Conceitos de REST DÚVIDA: Utilizar singular ou plural? Exemplos: Não existe uma regra específica sobre isso, mas deve ser definido um padrão: Todas as URLs no plural ou todas no singular

30 Conceitos de REST Semântica de Recursos Passagem de parâmetros: Deve ser possível passar parâmetros separados por barras ou consulta; Exemplo: Se desejarmos buscar um usuário pelo CPF utilizando path parâmeters, devem ser possível realizar uma requisição como segue: /usuário/ Também é possível utilizar o formato de query parameters: /usuário?cpf=

31 Conceitos de REST Semântica de Recursos Passagem de parâmetros: Outros formatos: Matrix parameters semelhantes aos query parameters, mas utilizados quando os parâmetros têm relação entre si, e são separados por ponto e vírgula: /endereco;numero=12;cep= Form parameters dados gerados a partir de formulários HTML; Head parameters dados passados para o servidor via cabeçalho HTTP; Body parameters utilizados para passagem de dados em métodos específicos, como no POST. Os parâmetros estão contidos no corpo da requisição

32 Conceitos de REST Interação por métodos A regra de ouro é que URLs são substantivos e os métodos HTTP são verbos; Os métodos HTTP são responsáveis por causar alterações nos recursos que as URLs identificam; ATENÇÃO: A URL não deve mudar de acordo com a operação; O que mudam são os métodos e os parâmetros; 32 32

33 Conceitos de REST Interação por métodos Para realizar um CRUD (create, retrieve, update, delete): 33 33

34 Conceitos de REST Representações distintas Aqui cabem novamente PARÊNTESIS: Você sabe diferenciar JSON e XML? JavaScript Object Notation; Extended Markup Language; 34 34

35 35 FIGHT! FIGHT! FIGHT!

36 Conceitos de REST Representações distintas (PARÊNTESIS): JSON e XML são formatos de dados! Sua API REST pode retornar qualquer formato de dados: JSON, XML, CSV, etc; São padrões para estruturar o conteúdo que será retornado ao acessar a URL de um recurso; Um não é melhor ou pior que o outro: ambos têm vantagens e desvantagens para utilização em contextos diferentes; XML é mais rico em fornecer metadados; JSON é mais simples e não permite tipificar dados ou fornecer metadados (mas é possível estender o formato para fazer isso); JSON se tornou mais popular por ser mais simples para entendimento e interpretação, mais leve (pois os arquivos têm menor tamanho) e mais práticos para realizar sua manipulação; 36 36

37 Conceitos de REST Representações distintas (PARÊNTESIS): Alguns conceitos errados que devem ficar BEM claros hoje: XML não é: O futuro! coisa de java ; HTML; Linguagem de programação; JSON não é: Protocolo; API nem é o REST em si; Solução pra tudo; Modinha ; 37 37

38 38

39 Conceitos de REST Representações distintas Continuando: O uso de cabeçalhos que informem media types nos permite definir como o recurso que desejamos será apresentado; Exemplos: Se quisermos representar o recurso /minicurso em XML, devemos informar o cabeçalho Accept com o valor application/xml; Se quisermos representar este mesmo recurso em JSON, devemos informar cabeçalho Accept com o valor application/json; Existem outras formas de definir a representação de um recurso, como adicionar uma extensão de arquivo à URL. Exemplos: /minicurso.json /minicurso.xml 39 39

40 Conceitos de REST Representações distintas Exemplo: Acessando a URL do recurso /participante/1 XML: JSON: 40 40

41 Conceitos de REST Uso correto dos códigos de status: Devemos aplicar os códigos de status no retorno das requisições, de acordo com a situação; Exemplo: Se acessamos à URL /minicurso com o método GET para listar todos os minicursos esta operação foi realizada com sucesso no backend, nossa requisição deve retornar com o status 200; 41 41

42 Arquitetura utilizando uma API REST 42 42

43 Arquitetura utilizando uma API REST 43 43

44 #comofaz? Implementação em PHP: Definir os cabeçalhos: Utilização da função header() Definir status code: Utilização da função http_response_code()

45 #comofaz? Implementação em PHP: Receber parâmetros: Utilização das super globais $_GET, $_POST e $_REQUEST: Identificar o método: Utilização da super global $_SERVER:

46 #comofaz? Implementação em PHP: Mãos à obra! Vamos implementar uma API REST simples com PHP puro (sem uso de frameworks); Para este curso vamos utilizar os seguintes softwares: Pacote XAMPP, contendo: PHP 5.6; Apache 2.2; MySQL 5.7; Visual Studio Code; Google Chrome; Cliente para executar as requisições: OU Advanced REST Client; OU Postman; 46 46

47 #comofaz? Agora vamos implementar! O código produzido será disponibilizado após o curso em: Banco de Dados II - Introdução, revisão e conceitos

48 48

49 Referências 1. SAUDATE, Alexandre. REST Construa APIs inteligentes. Ed. Casa do Código. Capítulos 1 a 3. Páginas1 a The PHP Group. Manual do PHP. Disponível em < Acesso em 27/05/2017; 3. JSON.org. Introdução ao JSON. Disponível em < Acesso em 27/05/2017; 4. Treina Web. REST não é simplesmente retornar JSON. Disponível em < Acesso em 27/05/2017; 5. ImgFlip. Meme Generator. Disponível em < Acesso em 27/05/2017; Projeto de Sistemas de Informação - Introdução e Revisão

50 Minicurso de REST Aula 1 Eder Martins Franco efranco23@gmail.com Este trabalho está licenciado sob uma Licença Creative Commons Atribuição-NãoComercial-CompartilhaIgual 4.0 Internacional. Para ver uma cópia desta licença, visite