---
title: "Web APIs"
bibliography: ../config/refs.bib
csl: ../config/ABNT-UFPR-2011-Mendeley.csl
output:
  beamer_presentation:
    # keep_md: true
    keep_tex: true
---

```{r, include = FALSE}
source("../config/setup.R")
# opts_chunk$set(eval = FALSE)
```

## Introdução

### Motivação

  1. Web API é a forma padrão de conferir acesso para usuários e entre
     aplicações.
  2. É usado por várias empresas:
     * Social: [Google], [Facebook], [Twitter], [Spotify], [Deezer],
       [Instragram], etc.
     * Esportes: [Soccer], [FIFA], [API-football], [Dota], [Xbox], etc.
     * Outras: [Coinbase], [Skyscanner], [Text-processing], etc.
     * Catálogo com milhares de APIs: [Rapid API].
  3. Níveis de acesso variado: *open & free*, *free* mas com registro,
     *freemium*, registro, pagas, privadas, etc.
  4. Resultados: em XML e JSON principalmente.
  5. APIs podem ser REST ou SOAP.

## Introdução

### Objetivos

  1. Definir o que Web API.
  2. Ilustrar o funcionamento.
  3. Mostrar algumas APIs.

## Exemplos de APIs

  * [Nominatim].
    * HTML: <https://nominatim.openstreetmap.org/search?city=Curitiba>.
    * XML:<https://nominatim.openstreetmap.org/search?city=Curitiba&format=xml>.
    * JSON: <https://nominatim.openstreetmap.org/search?city=Curitiba&format=json>.
  * [USGS Earth Quakes].
    * XML: <https://earthquake.usgs.gov/fdsnws/event/1/query?format=xml>.
    * GeoJSON: <https://earthquake.usgs.gov/fdsnws/event/1/query?format=geojson>.

## Definição

  * API: *Application Program Interface*.
  * Aplicação.
    * Web (site/url), móvel (app) ou software (pacote
      R/Python), etc.
    * Envia os inputs e recebe os outputs.
    * Parte executada no cliente.
  * Programa.
    * Transforma os inputs recebidos em outputs.
    * Parte executada no servidor.
  * Interface.
    * Como que a aplicação se comunica com o programa.
    * Forma de envio e conteúdo do input e retorno do output.
    * Envolve rede, protocolos, transferência, encriptação, validação,
      etc.

## Esquema de funcionamento geral

```{r, echo = FALSE, out.width = "9cm", fig.cap = cap}
cap <- "Como funciona uma API. Fonte: \\url{https://medium.com/@ama.thanu/what-is-an-api-how-does-it-work-f4ea552d741f}."
knitr::include_graphics("./img/3h95bN2_xe-eitwHh_Ygvw.png")
```

## Componentes de uma API

```{r, echo = FALSE, out.width = "10.5cm", fig.cap = cap}
cap <- "Aspectos gerais de uma API. O que é compartilhado entre cliente e servidor. Fonte: \\url{https://www.upwork.com/hiring/development/intro-to-apis-what-is-an-api/}."
knitr::include_graphics("./img/upwork-1.png")
```

## Modelo de negócio

```{r, echo = FALSE, out.width = "10.5cm", fig.cap = cap}
cap <- "Como uma API funciona em termos de modelo de negócio. Fonte: \\url{https://www.upwork.com/hiring/development/intro-to-apis-what-is-an-api/}."
knitr::include_graphics("./img/upwork-2.png")
```

## Anatomia da consulta

```{r, echo = FALSE, out.width = "8.5cm", fig.cap = cap}
cap <- "Anatomia de uma consulta a API. Fonte: \\url{https://medium.com/@shivamdesai_65083/fetching-data-from-rest-apis-with-react-25a2f6db5d7a}."
knitr::include_graphics("./img/HSiyldPgmLzQv_rOd55inw.png")
```

## Detalhes sobre o uso da API do Nominatim

```{r, echo = FALSE, out.width = "8.5cm", fig.cap = cap}
cap <- "Aspectos da requisição a API do Nominatim para a consulta da localização de Curitiba. Fonte: o autor."
knitr::include_graphics("./img/openstreetmap-request.png")
```

## Tipos de resultado

  * XML e derivados.
    * *eXtensible Markup Language*.
    * Estrutura hierárquica.
    * Campos de dados e metadados (atributos).
    * Muito verboso mas boa taxa compreesão.
    * Linaguem de consulta própria: XPath.
    * Vários parsers.
  * JSON, GeoJSON e derivados.
    * *JavaScript Object Notation*.
    * Estrutura hierárquica.
    * Campos para dados mas não tem atributos.
    * Menos verboso.
    * Vários parsers.
  * Outros: CSV, texto pleno, etc.

## Dados públicos abertos e API

  * APIs são um jeito seguro de fornecer acesso a dados públicos.
  * Simplifica para o usuário fazer a consulta.
  * O fornecedor porde escolher o deseja expor.
  * Pode controlar o volume de requições por usuário.
  * Pode rastrear quem faz uso dos dados.
  * Com isso a população pode consumir e auxiliar decisões públicas com
    base em dados.

## API tipo REST vs SOUP

Aspectos bem técnicos mais voltados para o desenvolvedor de APIs.

  1. <https://www.youtube.com/watch?v=TvGLm7BijJY>.
  2. <https://www.infoq.com/br/articles/rest-soap-when-to-use-each>.
  3. <https://www.devmedia.com.br/web-services-rest-versus-soap/32451>.

## Resumo

  * Web API é um mecanísmo comum para dar acesso a bases de dados e
    comunicar serviços.
  * XML e JSON são os formatos mais utilizados pelas Web APIs.
  * As APIs tem nível de acesso variado.

<!------------------------------------------- -->

[API-football]: https://www.api-football.com/
[Coinbase]: https://rapidapi.com/stefan.skliarov/api/Coinbase
[Deezer]: https://rapidapi.com/deezerdevs/api/deezer-1
[Dota]: https://docs.opendota.com/#
[FIFA]: https://rapidapi.com/montanaflynn/api/fifa-world-cup
[Facebook]: https://developers.facebook.com/docs/apis-and-sdks/
[Google]: https://cloud.google.com/apis/
[Instagram]: https://www.instagram.com/developer/
[Nominatim]: https://nominatim.org/
[Rapid API]: https://rapidapi.com/
[Skyscanner]: https://rapidapi.com/skyscanner/api/skyscanner-flight-search
[Soccer]: https://rapidapi.com/sportsop/api/soccer-sports-open-data
[Spotify]: https://developer.spotify.com/documentation/web-api/
[Text-processing]: https://rapidapi.com/japerk/api/text-processing
[Twitter]: https://developer.twitter.com/en/docs.html
[USGS Earth Quakes]: https://earthquake.usgs.gov
[Xbox]: https://xboxapi.com/
