O que é uma API?

Você sabe o que é uma API? Sabe por que é importante usar APIs do seu framework favorito? Conhece os conceitos de interfaces e caixa preta? Neste post vamos falar sobre esses assuntos dando uma olhada em alguns exemplos.

Comecei a pensar em um texto sobre os motivos de se usar as APIs do WordPress, mas precisei voltar em tantos conceitos que acabei na separação dos continentes no conceito básico do que é uma API. Esse post é tanto para você, dev sandy/junior, quanto para a galera sênior. E sim, vamos falar de conceitos, mas fique por aí porque estes são importantes.

API é a sigla para Application Programming Interface, ou seja, Interface de Programação de Aplicações. Mas o que isso quer dizer?!

"Programação" e "aplicações" são as partes fáceis. É o "interface" que a gente precisa entender melhor.

O que é uma Interface?

Interface nada mais é do que a casquinha de fora de alguma coisa, a parte que se conecta com o exterior, mantendo o interior protegido.

Nós lidamos com esse conceito todos os dias e, se não fosse por ele, a gente surtaria. Imagine ter que saber os detalhes de como cada coisa ao nosso redor funciona! Alguns exemplos de interfaces:

• Interface gráfica: Você clica, o programa faz. Não precisa saber como ele faz, o importante é clicar no botão e ele realizar a ação que você espera.
• Atendimento em um restaurante: Você faz o pedido, recebe a comida. Não importa quantos são os cozinheiros, a cor da panela ou a marca do fogão.
• Sistema sensorial do corpo humano: Você não precisa fazer ideia de como o seu corpo faz com que você sinta cheiros ou o gosto da comida, ele vai fazer isso por você.

A ideia inteira é baseada no conceito de entradas (inputs) e saídas (outputs). Dada uma entrada se espera uma saída, independente da implementação:

Todo esse conceito de entrada-e-saída-não-interessa-a-implementação se chama caixa preta. Há uma diferença importante aqui:

• Caixa preta é como chamamos algo que aceita uma entrada e retorna uma saída, sem necessariamente revelar como fez o processamento.
• Interface é a forma como você se conecta com o sistema, qual é exatamente a entrada esperada (um número, dois números, uma string) e como será a saída (outro número, outra string). É como um contrato.

Interfaces na programação

Aqui um breve parênteses. Além da letra I em API, ouvimos muito falar de interfaces em Orientação a Objetos. A ideia é exatamente a mesma: se uma classe diz que implementa uma determinada interface, ela obrigatoriamente precisa implementar os métodos daquela interface. Vou deixar aqui o link para a documentação oficial do PHP sobre interfaces, mas deixe um comentário se esse é um assunto que você gostaria de ver em outro post.

Ah, e tem também a WP-CLI, que é a interface de linha de comando :)

Tudo bem. A gente pode voltar a falar sobre APIs agora?

E é agora que vai começar o post! Vamos voltar à sigla:

Interface (conjunto de métodos com entradas e saídas cuja implementação não interessa)
de Programação (só dá para acessar programando)
de Aplicações

Ficou mais fácil agora?

APIs do WP

Quando eu tive a ideia de escrever esse post, eu queria falar sobre a importância de se utilizar APIs internas no WordPress. O WordPress tem várias dessas APIs, inclusive já falamos de algumas delas por aqui: a API dos transients e a API de configurações são alguns exemplos. A lista completa de APIs do WordPress está disponível em https://developer.wordpress.org/apis/.

Mas por que devemos usar essas APIs ao invés de simplesmente gravar alguma coisa diretamente no banco de dados ou salvar um arquivo no servidor?

São vários os motivos, vamos ver alguns deles aqui embaixo.

Importante: esses conceitos não são isolados, mas complementares entre si. Também não tentei cobrir todos os aspectos, então sinta-se a vontade para explorar qualquer outro aspecto na seção de comentários.

Separação de responsabilidades

O termo em inglês é Separation of concerns e a tradução varia entre separação de responsabilidades, separação de conceitos e separação de preocupações. Esse princípio visa separar a aplicação em módulos, cada um responsável por uma coisa. Esses módulos se comunicam através de — você adivinhou — interfaces. Dessa forma, um código que cria um produto fica separado do código que lida com pedidos que, por sua vez, só chama o módulo responsável por gravar o pedido em algum lugar.

Há muitos anos, infelizmente era comum ver aplicações em PHP com várias chamadas a mysqli_real_connect e similares. Hoje essa não é mais a realidade. No WordPress, por exemplo, temos a classe wpdb , outros frameworks usam ORM, mas sempre que é necessário gravar/salvar algum dado existe uma camada de abstração.

Legibilidade

Nós não escrevemos código para computadores, mas para outros seres humanos, afinal "código é poesia" não é à toa. Por isso é importante que seja fácil olhar para um código pela primeira vez e entender o que ele faz.

O que é mais fácil de entender? Isso

<?php
global $wpdb;
$wpdb->query(
    $wpdb->prepare(
        "INSERT INTO `$wpdb->options` (`option_name`, `option_value`, `autoload`)
            VALUES (%s, %s, %s)
            ON DUPLICATE KEY
            UPDATE
                `option_name` = VALUES(`option_name`),
                `option_value` = VALUES(`option_value`),
                `autoload` = VALUES(`autoload`)", 
        $option,
        $serialized_value,
        $autoload
    )
);

ou isso?

<?php
update_option( 'my_option', 'value' );

A segunda opção, certo? Fica fácil de entender que estamos salvando uma opção e se quisermos usar outro mecanismo de armazenagem como Redis ou Memcached (mais sobre isso abaixo), a parte do programa que está chamando a função update_option() não precisa ser alterada.

Exemplos práticos

Usar as APIs do WordPress facilitam a vida. Muitas vezes, não usar as APIs inviabilizam o projeto.

A API de arquivos

Esse é um caso clássico. A pessoa programa o salvamento de arquivo usando as funções fopen, fclose, etc. e tudo funciona bem. O projeto cresce um pouco, a infraestrutura precisa aumentar e os arquivos começam a desaparecer. Vamos dar uma olhada em alguns diagramas para entender melhor.

Salvando direto no servidor (com só um web server)

Até aqui dá tudo certo. O administrador enviou o arquivo para o único servidor e, quando o usuário visitar o site, o arquivo vai estar lá.

Salvando direto no servidor (com mais de um web server)

Agora vamos supor que é preciso acrescentar um servidor. Na frente dos dois servidores colocamos um Load balancer, para direcionar o tráfego ora para um, ora para outro.

Se salvarmos o arquivo direto no servidor, ele só ficará gravado no servidor onde o usuário administrador enviou o arquivo, não sendo encontrado toda vez que a requisição é feita para outro web server.

Salvando em um outro lugar

A solução normalmente é salvar os arquivos em outro lugar, como por exemplo um Bucket S3 da Amazon. Poderia ser qualquer outro lugar, o importante é que seja um lugar acessível por todos os servidores.

Como fazer isso?

A solução para esse nosso exemplo é simples, é só usar um plugin.

O importante é que o plugin só vai funcionar no código que estiver usando a API de arquivos do WordPress. Ele não vai ser capaz de alterar as chamadas diretas a fopen, só chamadas a $wp_filesystem->put_contents() ou funções que passem pela API do WordPress.

A API de transients

Se você ler o post sobre a API de transients e a documentação oficial vai ver que ela basicamente consiste em três funções: set_transient(), get_transient() e delete_transient(). Você poderia implementar três funções para salvar, pegar e excluir valores do banco de dados rapidamente, mas estaria perdendo uma das peças de infraestrutura usadas para melhoria de desempenho: armazenamento em memória.

Calma, eu explico. Quando falei sobre tipos de plugin, falei sobre os drop-ins e um deles é o object-cache.php. Com ele, é possível usar softwares como o Redis ou o Memcached, que guardam coisas na memória, ao invés de usar o disco. Acesso a memória é muito mais rápido que acesso a disco e, por isso, esses programas retornam coisas mais rápido que o banco de dados.

Se você estiver gravando coisas direto no banco de dados, colocar algo assim na sua infraestrutura não fará diferença. Por outro lado, se estiver usando a API do WordPress, basta instalar e configurar um plugin com o seu drop-in e as coisas passarão a funcionar automaticamente. Inclusive, se precisar trocar entre o Redis e o Memcached, a implementação faz isso para você, afinal você está só usando a interface.

A API REST do WordPress

Eu já falei desse assunto antes, há alguns anos, mas ele ainda continua muito atual. Se você chegou até aqui querendo saber mais sobre a API REST do WP dá uma olhada nesse outro post. Tenho certeza de que você vai curtir!

---

O post ficou gigante, eu sei. Se puder compartilhar nas suas redes sociais, assinar a newslette e deixar um comentário você ajuda demais. MUITO OBRIGADO!