🥇 APIs de hipermídia

Uma ‘API de hipermídia’ é aquela em que a arquitetura da API é semelhante à arquitetura da rede mundial de computadores.

Prós

Projetado para escala. Essa arquitetura foi comprovada nos últimos 20 anos e aciona o maior sistema de informações já criado.
Tolerante à mudança. Compatibilidade com versões anteriores e posteriores são incentivados por meio do desacoplamento de componentes
O encapsulamento de componentes permite construir sistemas maiores a partir de sistemas menores.

Contras

Se você precisa de uma latência inferior a 100 ms, esta não é a sua arquitetura.
O cache é muito usado. “Existem duas coisas difíceis na ciência da computação: invalidação de cache, nomenclatura e erros de desconexão.”
O favorecimento dos formatos de texto significa que as mensagens individuais podem não ser tão pequenas quanto os formatos binários.

Notas de implementação do servidor

As duas regras fundamentais:
1. Respeite o HTTP
2. Use um tipo de mídia hipermídia

Respeite HTTP

Obedeça o espírito da RFC 2616 , não a letra. Leia as especificações ao invés de blogs. É bastante legível.

Não confie no que você pensa que sabe, provavelmente está errado. Ou, pelo menos, não 100% preciso. Exemplo: PUT requer uma representação de substituição completa, não apenas parcial. PUT também pode ser usado para criar recursos, é um ‘upsert’ e não uma ‘atualização’.

Para obter esclarecimentos sobre muitos problemas, consulte httpbis .

Se você estiver interessado no raciocínio por trás da criação do protocolo, verifique a dissertação de Fielding . Às vezes, conhecer os primeiros princípios pode ajudar a explicar decisões de design “estranhas”.

Tipos de mídia hipermídia

Você tem duas opções principais para um tipo de hipermídia.

Use um tipo existente
Construa o seu próprio

Use um tipo existente

Tipos comuns:

Construa o seu próprio

Dois caminhos: Faça um tipo personalizado ou use a relação de link de perfil.

Se você gostaria de fazer um tipo personalizado, leia Construindo APIs de hipermídia em HTML5 e Nó . Construir um tipo personalizado é tanto arte quanto ciência.

Para adicionar um sabor hipermídia a um tipo (geralmente JSON), verifique este rascunho da Internet: O tipo de relação de link ‘perfil’

Notas de implementação do cliente

Implemente o tipo de mídia, não as respostas de um servidor específico.
Conte apenas com o que está na definição do tipo de mídia, nada mais.
Se possível, faça dois serviços que atendam ao tipo e teste seu cliente em relação a ambos.
Seja flexível: não dependa muito da estrutura. Use //em xpath, por exemplo.
Implementar cache local. A solicitação mais eficiente é aquela que nunca usa a rede.