O que é uma API? E uma Interface?

Um termo bastante falado em computação é API. Normalmente, quando ele aparece, logo se fala de coisas como REST, HTTP, frameworks e etc. Pouco depois, a conversa cai no framework favorito da pessoa que está escrevendo ― Flask? Django REST Framework? Phoenix? Rails?? ― existe uma infinidade deles! Além disso, existe também uma infinidade de conceitos relacionados à arquitetura de API usada ― REST? SOAP? ― ao protocolo de comunicação usado ― HTTP? ― enfim, é uma conversa longa e cheia de caminhos possíveis.

Cada um desses conceitos merece atenção. Hoje, eu vou falar só do primeiro deles, a tal API. API é uma sigla ― Interface de Programação de Aplicações. Vou dar um "zoom" maior ainda e me focar em apenas uma palavra da sigla: interface.

Interfeice vs Interfáce

A palavra interface pode ser pronunciada de duas formas diferentes. Em Inglês, "interfeice" ou de forma mais aportuguesada, "interfáce". O acento não existe, é apenas para marcar que a segunda pronúncia faz referência à face, rosto, frente.

Quando falamos sobre interfaces, falamos de uma interação entre duas entidades, entre duas coisas diferentes, entre duas faces diferentes. Note o prefixo "inter", como em "internacional" ou "interestadual". Entre nações, entre estados e entre faces. Por fim, quando falamos em APIs, falamos em interfaces entre sistemas computacionais.

Interfaces Físicas e Computacionais

Em nosso dia-a-dia, interagimos com diversas interfaces físicas. O controle-remoto de uma televisão, os botões de uma cafeteira, o interruptor de um ventilador. Todos são exemplos de entidades que fazem a ponte entre o usuário e um outro recurso ― são interfaces.

Em nossos computadores, também temos diversas interfaces ativas à todo momento. O fato delas serem computacionais, porém, não significam que elas são APIs.

Uma API é uma interface computacional muito especial. Relembrando, a sigla significa "Interface de Programação de Aplicações". A característica fundamental de uma API é que ela é uma interface programável. Nós podemos, através de APIs, conectar diferentes pedaços de software uns aos outros, criando novas combinações e novas possibilidades.

Você pode alegar, corretamente, que você consegue escrever um código que aperta os botões da calculadora! Isso seria uma API certo? Não exatamente. Observe, a calculadora do meu sistema operacional não oferece nenhuma facilidade para que outro software utilize dela. Ela não foi feita para isso.

APIs permitem que softwares conectem-se entre si e utilizem as capacidades uns dos outros

Exemplos

Quando você utiliza uma biblioteca ou até mesmo uma função, ela expõe para você uma interface. A função sorted do Python, por exemplo, ela possui uma habilidade ― ordenar sequências ― que você pode querer usar em seu código. Os argumentos da função são o "rosto público" desse recurso.

‌Bibliotecas complexas como o NumPy expõem uma série de recursos na forma de funções, classes e módulos. Mais uma vez, os nomes, atributos e argumentos dessas entidades são a "face pública" de um recurso computacional que você pode usar em seu código.

Externo & Interno

Até aqui, desenvolvi a ideia da interface como sendo o "rosto público" de alguma entidade. Existe uma consequência importante dessa definição:

uma interface oculta as complexidades desnecessárias do recurso enquanto exibe uma face pronta para o usuário, que não precisa se preocupar com os detalhes.

Tome a função sorted que dei como exemplo ali em cima. Por baixo dos panos, ela é uma função em C embutida na linguagem Python, que se preocupa com diversos detalhes que não são necessários ao usuário da função. Um interface — e por consequência, uma API — bem feitas exibem o que é necessário, enquanto ocultam o que é irrelevante. Decidir onde traçar a linha entre o fundamental e o supérfluo é um problema na hora de arquitetar APIs (e muita gente tem opiniões muito fortes sobre isso!).

Documentação

Não é acidental que os dois exemplos que dei, eu mostrei print de uma documentação. Se uma API é uma interface pública e você não publica ela de forma alguma, quão útil ela de fato é? Ora, uma face pública que ninguém sabe como funciona, não é exatamente útil!

Documentação de código e de APIs é outro ponto que merece uma série de artigos só para si. Porém, quero deixar um recado importante para quem está começando nesse mundo

Uma API é tão útil por terceiros quanto melhor for a sua documentação. Uma face pública escondida, não é tão pública assim e não cumpre exatamente com seu papel.

HTTP, REST & a Web

Como vocês podem notar nos exemplos anteriores, não precisamos falar de Internet ao discutirmos APIs. No entanto, a Internet é um meio extremamente importante de conexão entre recursos computacionais diferentes. Portanto, um número gigantesco de APIs ― e de artigos sobre APIs ― é focado na web.

Eu quis escrever esse texto sem tocar nesses assuntos pois eles são densos e eu senti falta de um texto que lida com APIs sem pular para a Internet. No futuro, devo autorar mais materiais sobre essa parte.

Por hora ― e para satisfazer a curiosidades das eventuais pessoas decepcionadas por eu não ter tocado nisso ainda ― vou dar um breve resumo.

O protocolo HTTP define uma linguagem para que computadores se conversem. Nós podemos utilizar dessa linguagem pronta na hora de pensarmos numa API. Por exemplo, o HTTP vai nos dar formas estruturadas de comunicar erros — alguém pediu por algo que não existe? Retorne o famoso HTTP-404 ao invés de criar a sua solução customizada de erro!

O HTTP também nos dá formas robustas de responder perguntas do tipo "eu preciso servir esse texto. Ele possui traduções completas em 3 idiomas diferentes e traduções parciais em outros 5. Qual tradução do texto eu ofereço ao usuário?". De novo, ao invés de criarmos uma solução complexa, podemos utilizar das facilidades testadas ao longo do tempo que o HTTP nos oferece para isso.

REST, por outro lado, tem mais relação com estruturação, com a arquitetura da aplicação. Existe muito abuso de notação quando lidamos com REST mas, para um breve resumo, o REST vai nos facilitar pensar sobre as entidades que nossa aplicação contém e como arquitetar suas partes.

Um exemplo web

Um exemplo simples de API web é o MathJS. Ela permite que a gente tenha uma calculadora verdadeiramente programável e pela internet. Essa URL, por exemplo:

https://api.mathjs.org/v4/?expr=21*2

Irá retornar 42, o resultado da expressão 21*2. Observe como esse "site" aceita explicitamente um cálculo matemático através de um texto e retorna também um texto simples como resposta. Podemos, por exemplo, facilmente acessar esse recurso através de um terminal, com um comando como curl "https://api.mathjs.org/v4/?expr=21*2"

Como você pode ver, tanto pelo navegador, quanto pelo terminal, você consegue o resultado. O MathJS expõe uma API através do protocolo HTTP, uma língua que o seu navegador e o curl também falam.

Uma Reflexão sobre Conectividade na Web

‌Por fim, eu recomendo fortemente esse vídeo maravilhoso — e relativamente curto — sobre a história recente da interconexão de serviços na Internet.

Resumo

APIs são um assunto importantíssimo e grande. Como todo assunto que cumpre esses dois quesitos, existem muitos recortes que a gente pode fazer ao falar deles. Nesse texto eu quis focar na seguinte ideia:

APIs não são nada mais do que interfaces especiais e, como tal, devem ser vistas como a face externa de um recurso computacional.

APIs servem para interconectar recursos computacionais, permitindo que o seu código utilize recursos de outros serviços.

Agradeço aos meus colegas de Computação-UNICAMP ― Gabriel Lima, Ian Loron, Dede, Júlio e Murilo ― pela revisão e feedbacks