O que é uma API?
Tags: braziliandevs, api, wordpress, php
Published: 2022-06-21 23:52:04

<!-- wp:paragraph -->
<p>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.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>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. <strong>Esse post é tanto para você, dev sandy/junior, quanto para a galera sênior.</strong> E sim, vamos falar de conceitos, mas fique por aí porque estes são importantes.</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><p>API é a sigla para <strong>Application Programming Interface</strong>, ou seja, Interface de Programação de Aplicações. <strong>Mas o que isso quer dizer?!</strong></p></blockquote>
<!-- /wp:quote -->

<!-- wp:image {"align":"center","id":2025,"sizeSlug":"medium","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-medium"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/confused-macgyver.png"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/confused-macgyver-300x225.png" alt="MacGyver confuso com a frase &quot;I don't understand&quot; escrita" class="wp-image-2025"/></a></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>"Programação" e "aplicações" são as partes fáceis. É o "interface" que a gente precisa entender melhor.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>O que é uma <em>Interface</em>?</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Interface nada mais é do que a casquinha de fora de alguma coisa, <strong>a parte que se conecta com o exterior</strong>, mantendo o interior protegido.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>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:</p>
<!-- /wp:paragraph -->

<!-- wp:list -->
<ul><li><strong>Interface gráfica:</strong> 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.</li><li><strong>Atendimento em um restaurante:</strong> 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.</li><li><strong>Sistema sensorial do corpo humano:</strong> 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ê.</li></ul>
<!-- /wp:list -->

<!-- wp:image {"align":"center","id":2008,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/caixa-eletronico.gif"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/caixa-eletronico.gif" alt="Mulher chegando a um caixa eletrônico aberto, com um homem sentado dentro fazendo contas para dar o dinheiro." class="wp-image-2008"/></a><figcaption>Colocar o cartão e a senha e receber o dinheiro é tudo o que precisa acontecer. Não importa se é uma máquina ou um cara fazendo contas.</figcaption></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>A ideia inteira é baseada no conceito de entradas (<em>inputs</em>) e saídas (<em>outputs</em>). Dada uma entrada se espera uma saída, independente da implementação:</p>
<!-- /wp:paragraph -->

<!-- wp:table {"className":"is-style-stripes"} -->
<figure class="wp-block-table is-style-stripes"><table><tbody><tr><td></td><td><strong>Entrada</strong></td><td><strong>Saída</strong></td></tr><tr><td>Interface Gráfica</td><td>Clique no botão</td><td>Ação desejada</td></tr><tr><td>Atendimento em um restaurante</td><td>Realização do pedido</td><td>Entrega da comida</td></tr><tr><td>Sistema sensorial do corpo humano</td><td>Toque na pele</td><td>Sensação relacionada (frio, calor, etc.)</td></tr><tr><td>Caixa eletrônico</td><td>Inserção de cartão e senha</td><td>Saída do dinheiro</td></tr></tbody></table></figure>
<!-- /wp:table -->

<!-- wp:paragraph -->
<p>Todo esse conceito de entrada-e-saída-não-interessa-a-implementação se chama <strong>caixa preta</strong>. Há uma diferença importante aqui:</p>
<!-- /wp:paragraph -->

<!-- wp:list -->
<ul><li><strong>Caixa preta é como chamamos algo que aceita uma entrada e retorna uma saída</strong>, sem necessariamente revelar como fez o processamento.</li><li><strong>Interface é a forma como você se conecta com o sistema</strong>, 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.</li></ul>
<!-- /wp:list -->

<!-- wp:image {"align":"center","id":2056,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/caixa-preta-e-interface.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/caixa-preta-e-interface.jpg" alt="" class="wp-image-2056"/></a></figure>
<!-- /wp:image -->

<!-- wp:heading {"level":3} -->
<h3>Interfaces na programação</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>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 <a href="https://www.php.net/manual/pt_BR/language.oop5.interfaces.php">link para a documentação oficial do PHP sobre interfaces</a>, mas deixe um comentário se esse é um assunto que você gostaria de ver em outro post.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Ah, e tem também a <a href="https://felipeelia.com.br/wp-cli-wordpress-na-linha-de-comando/">WP-CLI</a>, que é a interface de linha de comando :)</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Tudo bem. A gente pode voltar a falar sobre APIs agora?</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>E é agora que vai começar o post! Vamos voltar à sigla:</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><p><strong>Interface</strong> <em>(conjunto de métodos com entradas e saídas cuja implementação não interessa)</em><br><strong>de Programação</strong> <em>(só dá para acessar programando)</em><br><strong>de Aplicações</strong></p></blockquote>
<!-- /wp:quote -->

<!-- wp:paragraph -->
<p>Ficou mais fácil agora?</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":2037,"sizeSlug":"medium","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-medium"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/agora-eu-entendi-bender-meme.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/agora-eu-entendi-bender-meme-300x225.jpg" alt="" class="wp-image-2037"/></a></figure>
<!-- /wp:image -->

<!-- wp:heading -->
<h2>APIs do WP</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>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 <a href="https://felipeelia.com.br/cache-facil-no-wordpress-transients-api/">API dos transients</a> e a <a href="https://felipeelia.com.br/como-criar-uma-tela-de-configuracao-para-o-seu-plugin-wordpress-com-a-settings-api-parte-1/">API de configurações</a> são alguns exemplos. A lista completa de APIs do WordPress está disponível em <a href="https://developer.wordpress.org/apis/">https://developer.wordpress.org/apis/</a>.</p>
<!-- /wp:paragraph -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><p>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?</p></blockquote>
<!-- /wp:quote -->

<!-- wp:paragraph -->
<p>São vários os motivos, vamos ver alguns deles aqui embaixo. </p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p><strong>Importante:</strong> 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.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>Separação de responsabilidades</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>O termo em inglês é <em>Separation of concerns</em> 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, <strong>um código que cria um produto fica separado do código que lida com pedidos</strong> que, por sua vez, só chama o módulo responsável por gravar o pedido em algum lugar.</p>
<!-- /wp:paragraph -->

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

<!-- wp:image {"align":"center","id":2039,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/ruptura.gif"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/ruptura.gif" alt="" class="wp-image-2039"/></a><figcaption>A série "Ruptura" leva a separação de responsabilidades a um OUTRO nível.</figcaption></figure>
<!-- /wp:image -->

<!-- wp:heading -->
<h2>Legibilidade</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p><strong>Nós não escrevemos código para computadores, mas para outros seres humanos</strong>, 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.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>O que é mais fácil de entender? Isso</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>&lt;?php
global $wpdb;
$wpdb-&gt;query(
	$wpdb-&gt;prepare(
		"INSERT INTO `$wpdb-&gt;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
	)
);</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>ou isso?</p>
<!-- /wp:paragraph -->

<!-- wp:code -->
<pre class="wp-block-code"><code>&lt;?php
update_option( 'my_option', 'value' );</code></pre>
<!-- /wp:code -->

<!-- wp:paragraph -->
<p>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 <code>update_option()</code> não precisa ser alterada.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":2040,"width":576,"height":323,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/code-is-poetry.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/code-is-poetry.jpg" alt="" class="wp-image-2040" width="576" height="323"/></a><figcaption>Código é poesia!</figcaption></figure>
<!-- /wp:image -->

<!-- wp:heading -->
<h2>Exemplos práticos</h2>
<!-- /wp:heading -->

<!-- wp:quote -->
<blockquote class="wp-block-quote"><p>Usar as APIs do WordPress facilitam a vida. Muitas vezes, não usar as APIs inviabilizam o projeto.</p></blockquote>
<!-- /wp:quote -->

<!-- wp:heading -->
<h2>A API de arquivos</h2>
<!-- /wp:heading -->

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

<!-- wp:heading {"level":3} -->
<h3>Salvando direto no servidor (com só um web server)</h3>
<!-- /wp:heading -->

<!-- wp:image {"align":"center","id":2053,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-1-salvando-direto-no-servidor.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-1-salvando-direto-no-servidor.jpg" alt="" class="wp-image-2053"/></a></figure>
<!-- /wp:image -->

<!-- wp:paragraph -->
<p>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á.</p>
<!-- /wp:paragraph -->

<!-- wp:heading {"level":3} -->
<h3>Salvando direto no servidor (com mais de um web server)</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Agora vamos supor que é preciso acrescentar um servidor. Na frente dos dois servidores colocamos um <em>Load balancer</em>, para direcionar o tráfego ora para um, ora para outro.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>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.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":2054,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-2-salvando-direto-no-servidor.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-2-salvando-direto-no-servidor.jpg" alt="" class="wp-image-2054"/></a></figure>
<!-- /wp:image -->

<!-- wp:heading {"level":3} -->
<h3>Salvando em um outro lugar</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>A solução normalmente é salvar os arquivos em outro lugar, como por exemplo um <a href="https://aws.amazon.com/pt/s3/">Bucket S3 da Amazon</a>. Poderia ser qualquer outro lugar, o importante é que seja um lugar acessível por todos os servidores.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":2055,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-3-salvando-no-s3.jpg"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/api-arquivos-wp-parte-3-salvando-no-s3.jpg" alt="" class="wp-image-2055"/></a></figure>
<!-- /wp:image -->

<!-- wp:heading {"level":3} -->
<h3>Como fazer isso?</h3>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>A solução para esse nosso exemplo é simples, é só usar um <a href="https://github.com/humanmade/S3-Uploads">plugin</a>.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>O importante é que <strong>o plugin só vai funcionar no código que estiver usando a API de arquivos do WordPress</strong>. Ele não vai ser capaz de alterar as chamadas diretas a <code>fopen</code>, só chamadas a <code>$wp_filesystem-&gt;put_contents()</code> ou funções que passem pela API do WordPress.</p>
<!-- /wp:paragraph -->

<!-- wp:heading -->
<h2>A API de transients</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>Se você ler <a href="https://felipeelia.com.br/cache-facil-no-wordpress-transients-api/">o post sobre a API de transients</a> e a <a href="https://developer.wordpress.org/apis/handbook/transients/#function-reference">documentação oficial</a> vai ver que ela basicamente consiste em três funções: <code>set_transient()</code>, <code>get_transient()</code> e <code>delete_transient()</code>. 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: <strong>armazenamento em memória</strong>.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Calma, eu explico. Quando falei sobre <a href="https://felipeelia.com.br/tipos-de-plugin-do-wordpress/">tipos de plugin</a>, falei sobre os <em>drop-ins</em> e um deles é o <code>object-cache.php</code>. 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. <strong>Acesso a memória é muito mais rápido que acesso a disco</strong> e, por isso, esses programas retornam coisas mais rápido que o banco de dados.</p>
<!-- /wp:paragraph -->

<!-- wp:paragraph -->
<p>Se você estiver gravando coisas direto no banco de dados, colocar algo assim na sua infraestrutura não fará diferença. Por outro lado, <strong>se estiver usando a API do WordPress, basta instalar e configurar um plugin</strong> com o seu <em>drop-in</em> 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.</p>
<!-- /wp:paragraph -->

<!-- wp:image {"align":"center","id":2048,"width":480,"height":216,"sizeSlug":"full","linkDestination":"media"} -->
<figure class="wp-block-image aligncenter size-full is-resized"><a href="https://felipeelia.com.br/wp-content/uploads/2022/06/redis-object-cache-plugin.png"><img src="https://felipeelia.com.br/wp-content/uploads/2022/06/redis-object-cache-plugin.png" alt="" class="wp-image-2048" width="480" height="216"/></a><figcaption>Aqui no blog eu uso o <a href="https://br.wordpress.org/plugins/redis-cache/" target="_blank" rel="noreferrer noopener">Redis Object Cache</a></figcaption></figure>
<!-- /wp:image -->

<!-- wp:heading -->
<h2>A API REST do WordPress</h2>
<!-- /wp:heading -->

<!-- wp:paragraph -->
<p>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 <a href="https://felipeelia.com.br/a-api-rest-do-wordpress/">API REST do WP</a> dá uma olhada nesse outro post. Tenho certeza de que você vai curtir!</p>
<!-- /wp:paragraph -->

<!-- wp:separator -->
<hr class="wp-block-separator has-alpha-channel-opacity"/>
<!-- /wp:separator -->

<!-- wp:paragraph -->
<p>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!</p>
<!-- /wp:paragraph -->