O que é uma API — as pecinhas, e as mãos que as montam

Três letras que você ouve em todo lugar#

API. A API do Google, a API do WhatsApp, a Revit API. O nome completo é Application Programming Interface, e vamos ser sinceros: sozinho, não diz nada. Precisa de uma imagem, e a imagem certa você tem em casa desde os seis anos.

As pecinhas#

De um lado há uma caixa cheia de peças já construídas por outra pessoa. Em programação, essa caixa se chama biblioteca. Do outro lado está você, com as suas mãos: a linguagem de programação, no nosso caso Python. Dois mundos separados, as peças de outra pessoa e as suas mãos. Onde eles conversam?

Eles conversam no encaixe. Cada pecinha tem os pinos em cima e os tubos embaixo, e esses formatos são iguais para todas as peças da caixa. A API é exatamente isso: não são as peças, não são as mãos, é o formato dos encaixes.

Nome, entrada, saída#

1. como ele se chama;
2. o que você precisa entregar a ele;
3. o que ele devolve.

Pegue o encaixe “arredonda”: nome, arredonda; entrada, um número com vírgula; saída, o número inteiro mais próximo. Esse trio tem um nome preciso: se chama contrato. Se você sabe ler um contrato, sabe usar qualquer biblioteca do mundo.

E repare numa coisa: como a peça arredonda, que contas ela faz lá dentro, você não sabe e não precisa saber. A pecinha é fechada. Você usa o formato, nunca o conteúdo.

O seu dia está cheio de contratos assim. A tomada: dois furos, um formato igual para todos, entre quem oferece a energia e quem a usa. As APIs da web são a mesma ideia, só que a pecinha fica num computador distante.

E o Revit?#

A primeira montagem: contar as paredes#

• FilteredElementCollector: abre o fichário do modelo;
• OfClass: você diz que tipo de peça quer, as paredes;
• GetElementCount: você não entrega nada, e ele devolve um número.

Quarenta e dois. O modelo tem quarenta e duas paredes. Três linhas, nenhuma mágica: três contratos bem lidos.

E se você errar? Se passar ao collector uma palavra em vez do documento, o Revit responde com uma mensagem de erro. Essa mensagem é sua amiga: não é o código que quebra, é o contrato dizendo o que ele esperava.

O manual de instruções#

De onde vêm esses nomes? Toda caixa de LEGO tem o seu manual, e a caixa do Revit tem o dela: a documentação da Revit API, onde cada encaixe está escrito com nome, entrada e saída.

E a escada é sempre esta: primeiro você aprende a ler o modelo, depois a filtrar e contar, depois a escrever. Sempre nessa ordem, sempre com as mesmas pecinhas. A caixa não muda: muda o que você sabe montar.

Assista ao vídeo#

Nove minutos, do clique das pecinhas ao primeiro código, sem pré-requisitos. O vídeo mostra as peças se encaixando, o contrato lido linha por linha, a caixa do Revit se abrindo e o erro de verdade na tela. O vídeo está em italiano.

O vídeo completo está no YouTube: se você gostou, inscreva-se no canal e ative o sininho para os próximos episódios.