O documento discute projeto de APIs, abordando conceitos como aprendizado, programação, integração e boas práticas de projeto. É destacado que APIs devem ser intuitivas, focadas no usuário e ter testes para garantir a qualidade. O desenvolvimento deve seguir TDD, começando com casos de uso e testes para guiar o design.

1. Projeto
de
API
Gilmar
P.
S.
Leitão
@gilmatryx

2. ¡ Aprendendo
§ Definições
e
conceitos
¡ Programando
§ Iniciando
um
projeto
de
API
§ Princípios
de
projeto
§ Projeto
de
classes
¡ Integrando

3. ¡ APRENDENDO

4. ¡ Web
(SOAP,
REST,
etc)
¡ SO
(Unix,
Windows,
etc)
¡ Linguagens
de
Programação
(C++,
Java,
etc)
¡ Protocolos
(Java
–
RMI
à
IIOP)

5. É
uma
coleção
de:
§ Funções,
Classes,
Tipos
de
Dados
§ Eventos,
Protocolos,
Arquivos,
etc.
Onde
temos
um
sistema
Que
se
comunica
Com
outro
Através
dessas
Coleções

6. É
uma
coleção
de:
• Funções,
Classes,
Tipos
de
Dados
• Eventos,
Protocolos,
Arquivos,
etc.
Onde
temos
um
sistema
Que
se
comunica
Com
outro
Através
dessas
Coleções
Biblioteca,
Componente,
Framework,
Sistema
Operacional,
Recurso
na
Web,
Etc.

7. ¡ Application
Programming
Interface

9. Se
você
programa,
então
você
provavelmente
trabalha
com
módulos
ou
pelo
menos
deveria.
Bons
programas
são
modulares
e
cada
módulo
deve
ter
uma
API.
Pensar
em
termos
de
API
melhora
a
qualidade
do
código.

10. Uma
API
pode
ser
um
dos
maiores
tesouros
de
uma
empresa.
Clientes
investem
ao
integrar
uma
API.
"A
key
lesson
here
is
that
API
is
not
just
a
documented
class.
And,
APIs
don't
just
happen;
they
are
a
big
investment."
Erich
Gamma.

11. ¡ Clientes
investem:
comprando,
escrevendo
e
aprendendo
¡ APIs
promovem
a
reutilização
e
reduz
custos
¡ O
custo
em
parar
de
usar
uma
API
pode
ser
proibitivo
¡ APIs
públicas
de
sucesso
captam
clientes

12. APIs
também
podem
ser
um
dos
maiores
débitos
de
uma
empresa.
Podem
resultar
em
intermináveis
chamadas
ao
suporte.
”Public
APIs
like
diamonds,
are
forever.
You
have
one
chance
to
get
it
right
So
give
it
your
best."
Joshua
Bloch.

13.
Intuitiva

14. ¡ Fácil
de
aprender
¡ Fácil
de
usar,
mesmo
sem
documentação
¡ Difícil
de
usar
incorretamente
¡ Fácil
de
estender
¡ Fácil
de
ler
e
manter
o
código
que
a
usa
¡ Focada
em
um
propósito
¡ Poderosa
o
bastante
para
atender
os
requisitos
¡ Apropriada
e
direcionada
a
um
público
¡ Bem
documentada
(exemplar)

15. ¡ PROGRAMANDO

16. ¡ Iniciando
um
projeto
de
API
¡ Princípios
de
projeto
¡ Projeto
de
classes

17. 1) Liste
os
requisitos
2) Valide-­‐os
escrevendo
casos
de
uso
3) Escreva
código
para
cada
caso
de
uso
Faça
tudo
sob
a
perspectiva
do
usuário
da
API
Envolva
mais
pessoas
o
quanto
possível
nesse
processo

18. ¡ Escreva-­‐os
em
não
mais
do
que
uma
página
§ Quanto
menor
melhor
(estamos
começando)
§ Fácil
de
compartilhar
e
modificar
¡ Valide-­‐os
em
caso
de
uso
R:
Deveríamos
ter
um
programa
para
gerar
boletos
do
Bradesco
e
salvar
o
código
de
barras
no
banco
de
dados
para
controlar
a
cobrança.
Caso
de
Uso:
Gerar
boleto
para
banco
Bradesco
Caso:
Obter
código
de
barras
do
boleto
gerado
C:
Salvar
boleto
gerado
em
PDF

19. ¡ Codifique
o
mais
cedo
possível
¡ Comece
sem
realmente
implementar
Caso
de
Uso:
Gerar
boleto
para
banco
Bradesco
✓ Perspectiva
do
usuário
public
static
void
main..
{
Boleto
boleto
=
new
Boleto(Banco.Bradesco);
}
✓ Perspectiva
Implementação
class
Boleto{
private
String
codigoDeBarras;
...
}

20. Melhor
do
que
começar
a
implementar
cedo
é
começar
com
TDD
mesmo
para
rascunho
¡ Ajuda
manter
visível
apenas
o
que
interessa
¡ Gera
exemplos
de
uso
sempre
atualizados
¡ Direciona
o
design
¡ Evita
implementar
casos
que
seriam
descartados
¡ Evita
surpresas
desagradáveis

21. Além
de
usar
TDD
no
desenvolvimento
da
API
escreva
testes
para
o
código
que
utiliza
a
API
de
fato
Muitas
dependências,
métodos
complicados
e
outros
mal
cheiros
podem
ser
identificados
e
levar
o
design
à
uma
nova
direção

22. Golden
Rule
of
API
Design
”It’s
not
enough
to
write
tests
for
an
API
you
develop;
you
have
to
write
unit
tests
for
code
that
uses
your
API.
When
you
follow
this
rule,
you
learn
firsthand
the
hurdles
that
your
users
will
have
to
overcome
when
they
try
to
test
their
code
independently.”
Michael
Feathers,
(97
Things
Every
Programmer
Should
Know)

23. Caso
de
Uso:
Gerar
boleto
para
banco
Bradesco
public
void
deveGerarBoletoBradescoCorretamenteNaMinhaAplicacao(){
Boleto
boletoEsperado
=
mock(Boleto.class);
BoletoViewer
boletoViewer
=
mock(BoletoViewer
.class);
when(boletoViewer
.getBoleto()).thenReturn(boletoEsperado);
MeuGeradorDeBoleto
geradorDeBoleto
=
new
MeuGeradorDeBoleto(boletoViewer
);
Boleto
boletoGerado
=
geradorDeBoleto.gereBoletoCom(dadosDoMeuUsuario);
assertThat(boletoGerado,
equalTo(boletoEsperado));
}

24. Codifique
cedo
e
frequentemente
¡ Comece
antes
de
fato
implementar
(TDD)
¡ Escreva
testes
de
código
que
usa
API
¡ Escreva
exemplos
na
medida
que
progride
§ Lembre-­‐se
uma
API
boa
é
exemplar
§ Exemplos
bons
tornam
API
fácil
de
entender
§ Exemplos
ruins
disseminam
o
mal
uso,
geram
bugs,
perguntas
em
fóruns
e
+
problemas

25. Seja
realista
e
mantenha
o
foco
no
propósito
¡ Muitos
dos
projetos
de
APIs
são
restritivos
§ Não
tente
agradar
a
todos
§ Tente
desagradar
a
todos
igualmente

26. Tente
pensar
antecipadamente,
mas..
¡ Espere
por
cometer
erros
§ Em
poucos
anos
de
uso
da
API
eles
surgirão
§ Espere
por
evoluir
a
API

27. ¡ Iniciando
um
projeto
de
API
¡ Princípios
de
projeto
¡ Projeto
de
classes

28. API
deve
fazer
o
que
se
propõe
a
fazer
e
deve
fazer
bem
¡ Siga
o
princípio
de
responsabilidade
única
¡ Tente
manter
tudo
o
mais
simples
possível
¡ A
funcionalidade
deve
ser
fácil
de
explicar
§ Se
está
difícil
nomear,
algo
pode
estar
errado
§ Bons
nomes
guiam
o
desenvolvimento
§ Estar
suscetível
a
divisão
ou
fusão
de
módulos

29. API
deve
ser
o
mais
simples
possível,
mas
não
simplória
¡ Deve
satisfazer
os
requisitos
¡ Os
conceitos
extraídos
são
o
mais
importante
¡ Procure
uma
boa
proporção
de
poder/massa
¡ A
massa
conceitual
é
mais
importante
que
a
estrutural

30. API
deve
ser
tão
pequena
quanto
possível,
mas
não
a
menor
Na
dúvida,
deixe
de
fora
¡ Funcionalidades,
classes,
métodos,
etc
¡ Sempre
pode-­‐se
adicionar,
mas
não
remover
¡ Quanto
mais
coisa,
mais
difícil
de
se
aprender
¡ Quanto
mais
coisa,
mais
pode
dar
errado

31. Nomes
são
especiais
porque
eles
compõem
o
vocabulário
da
API
Escolha
nomes
pronunciáveis
e
memoráveis
¡ Bons
nomes
surgem
do
domínio
do
problema
§ São
familiares,
intuitivos
e
com
significado
¡
Bons
nomes
são
auto
explicativos
§ Evite
abreviações

32. Não
me
faça
pensar
O
código
deve
ser
lido
como
uma
prosa
Caso
de
Uso:
Gerar
boleto
para
banco
Bradesco
Boleto
boleto
=
Cobranca.gere()
.para(Banco.Bradesco)
.com(vencimentoAtual)
.com(valorAtual)
.boleto();
!
Código
que
usa
objetos
da
API
jrimum.org/bopepo

33. Seja
Consistente
¡ Mesma
palavra
=
significa
mesma
coisa
¡ Busque
simetria
e
consistência
§ Faça
a
mesma
coisa
do
mesmo
jeito
§ Por
toda
API,
plataforma,
ambiente,
etc
§ Inconsistência
aparece
por
que
você
mudou
de
ideia
com
o
tempo
§ Faça
revisões
de
código
para
manter
tudo
alinhado
com
o
time

34. Coisas
similares
devem
se
parecer
com
coisas
similares
Caso
de
Uso:
Gerar
boleto
para
banco
Bradesco
BoletoViewer
boleto
=
new
BoletoViewer(dados)
.comTemplate(arquivoPersonalizado)
.gerePdf();
Caso
de
Uso:
Gerar
guia
de
arrecadação
e
recebimento
banco
BB
GuiaViewer
guia
=
new
GuiaViewer(dados)
.comTemplate(arquivoPersonalizado)
.gerePdf();

35. Minimize
o
acesso
a
tudo
¡ Tudo
deve
ter
o
mínimo
privilégio
de
acesso
§ Promove
o
ocultamento
de
informação
§ Classes
e
membros
devem
ter
acesso
privado
sempre
que
possível
§ Classes
públicas
não
devem
ter
membros
públicos,
com
exceção
de
constantes

36. A
implementação
é
um
detalhe
¡ Detalhes
de
implementação
tem
impacto
§ Confundem
usuários
§ Dificultam
o
entendimento
¡ Saiba
identificá-­‐los
§ Parâmetros
para
otimização,
formato
de
dados
(file,
connection,
etc),
dependência
de
outras
APIs
¡ Não
deixe
vazarem
pela
API
§ Exceções,
formatos
de
dados,
etc

37. Documente
cedo,
frequentemente
e
sempre
¡ Documente
todo
parâmetro,
método,
construtor,
classe,
interface
e
exceção
¡ Mantenha
sempre
atualizada
¡ “O
que?”
e
“Como?”
devem
estão
sempre
presentes
¡ “Porque”
também
explicando
decisões
tomadas,
padrões
adotados,
etc

38. Documente
para
cada
situação
específica
¡ Documentação
de
referência
§ Javadoc
e
similares
¡ Tutorias
§ Como
começar
rapidamente
e
fazer
algo
de
valor
§ O
que
posso
fazer
em
2
minutos
§ Como
gerar
um
boleto
personalizado
¡ Guia
do
programador
§ Introdução,
glossário,
conceitos,
padrões,
etc

39. Sua
API
deve
ser
sinérgica
em
relação
a
Plataforma
¡ Faça
o
que
é
usual
e
convencionado
§ Siga
as
convenções
de
nomes
§ Imite
os
bons
padrões
das
APIs
da
linguagem
¡ Conheça
bem
a
plataforma
e
a
linguagem
§ Funcionalidades
amigáveis
devem
ser
utilizadas:
generics,
varargs,
enums,
default
arguments
¡ Também
conheça
armadilhas
e
ciladas
§ Finalizers,
permgen,
garbage
collector,
etc

40. Lembre-­‐se
que
decisões
no
projeto
poderão
afetar
a
performance
¡ Decisões
ruins
podem
limitar
a
performance
§ Fazendo
um
tipo
mutável
ou
imutável
§ Usando
uma
implementação
no
lugar
de
uma
interface
§ Oferecendo
um
construtor
no
lugar
de
um
factory
method

41. Lembre-­‐se
que
decisões
no
projeto
poderão
afetar
a
performance
¡ Decisões
ruins
podem
limitar
a
performance
§ Fazendo
um
tipo
mutável
ou
imutável
§ Usando
uma
implementação
no
lugar
de
uma
interface
§ Oferecendo
um
construtor
no
lugar
de
um
factory
method

42. ¡ Iniciando
um
projeto
de
API
¡ Princípios
de
projeto
¡ Projeto
de
classes

43. Quando
criar
um
tipo?
¡ Quando
existir
um
comportamento
específico
e
que
um
tipo
existente
não
suporte
¡ Quando
é
um
conceito
chave
no
domínio
Ex:
CEP,
CPF,
CodigoDeBarras,
Pagador,
Boleto,
..

44. Tipos
de
domínio
são
melhores
do
que
strings
”String
é
uma
estrutura
de
dados
rigorosa
e
exige
muita
duplicação
de
processo
em
qualquer
lugar
para
o
qual
seja
passada.
É
um
veículo
perfeito
para
ocultar
informações"
“The
string
is
a
stark
data
structure
and
everywhere
it
is
passed
there
is
much
duplication
of
process.
It
is
a
perfect
vehicle
for
hiding
information.”
Alan
Perlis.

45. Transforme
objetos
de
domínio
em
Objetos
de
Valor
(Tiny
Types
or
Value
Object
DDD)
¡ Projete-­‐os
imutáveis
a
menos
que
tenha
uma
boa
razão
para
o
contrário
Ex:
CEP,
CPF,
CodigoDeBarras,
Boleto,
..

46. Minimize
a
Mutabilidade
¡ Classes
devem
ser
imutáveis,
a
não
ser
que
haja
uma
boa
razão
para
fazer
o
contrário
§ Vantagens:
simples,
thread-­‐safe,
reutilizável
§ Desvantagens:
determina
um
objeto
para
cada
valor
¡ Se
mutável,
manter
o
espaço
de
estados
pequeno
e
bem
definido
§ Deixe
claro
quando
é
legal
chamar
qual
método.
Bom:
LocalDate,
Duration,
Instant
Ruim:
Date,
Calendar

47. Subclasse
somente
onde
faz
sentido
¡ Extensão
implica
em
substituição
(Liskov)
§ Estenda
somente
quando
o
relacionamento
"é
um"
existe
§ Do
contrário,
use
composição
¡ Classes
públicas
não
devem
estender
outras
classes
públicas
apenas
por
facilidades
de
implementação
Bom:
Set
extends
Collection
Ruim:
Properties
extends
Hashtable
Stack
extends
Vector

48. Projete
e
documente
para
herança
senão
a
proíba
¡ Herança
viola
o
princípio
de
encapsulamento
§ A
subclasse
é
suscetível
aos
detalhes
da
implementação
da
superclasse
¡ Se
você
permitir
a
extensão,
documente
a
auto-­‐utilização
§ Como
os
métodos
utilizam
um
outro?
¡ Política
conservativa:
todas
as
classes
concretas
são
final
Bom:
AbstractSet,
AbstractMap
Ruim:
Muitas
classes
concretas
em
libs
J2SE

49. ¡ Integrando

50. Um
servidor
de
integração
contínua
é
tão
dispensável
quanto
um
sistema
de
controle
de
versões
¡ Integração
contínua
§ Garante
que
o
código
continua
funcionando
após
cada
alteração
§ Proporciona
aos
participantes
do
projeto
a
visibilidade
do
estado
atual
do
projeto
✔
✖