APIs REST com bom design podem ser alavancadas para criarem aplicações web balanceadas entre clientes e servidores; aonde a responsabilidade do cliente se estende para muito além de simplesmente renderizar um documento HTML gerado por um servidor. Web sites e aplicativos tem mudado devagar para essa arquitetura desde quando o Internet Explorer 5 incluiu mecanismos AJAX, scripts DOM e XHR em seu núcleo. Recentemente, a mudança na arquitetura foi acelerada por avanços na performance dos processadores dos dispositivos e em interpretadores JavaScript, e também em diversos padrões – como o HTML5. Essa arquitetura é atrativa para as organizações por uma série de razões como:
☆ Melhores experiências – Aplicações ricas oferecem experiências mais aderentes.
☆ Menor tempo para lançamento no mercado – As camadas reutilizáveis das APIs REST servem para criar uma variedade de aplicações clientes, já que ela expõe os dados “crus” na Web, sem uma tela ou uma apresentação específica.
☆ Menor custo de operação – Requer menos servidores, já que clientes modernos podem lidar com uma grande fatia do processamento e do armazenamento das aplicações.
Para sustentar a complexidade constante das aplicações web construídas com essa arquitetura, as práticas de design e desenvolvimento aplicados às APIs REST precisam continuar amadurecendo.
REST e os tipos de mídia
Uma área do design de APIs REST que chama nossa atenção é o uso dos Tipos de Mídia (Media Types), que são também conhecidos como tipos MIME ou Tipo de Conteúdo (Content Types). Os tipo de mídia possuem a seguinte sintaxe: tipo “/” subtipo *(“;” parâmetro ) APIs REST geralmente trabalham com os tipos de mídia que se encaixam na categoria de aplicativos (“application”). Perceba que os parâmetros que vem a seguir do tipo e subtipo são na forma de pares: atributo=valor e são separados com ponto-e-vírgula. HTTP/1.1 utiliza os tipos de mídia nos valores dos cabeçalhos Accept e Content-Type.
Como ilustrado no exemplo a seguir, as aplicações clientes podem informar sua preferência por um tipo de resposta utilizando o cabeçalho Accept no protocolo HTTP/1.1:Accept: application/json,application/xml;q=0.9,text/html;q=0.8,*/*;q=0.7
No cabeçalho Content-Type de uma requisição ou de uma resposta HTTP/1.1, a referência do tipo de mídia indica o tipo do corpo da mensagem. O exemplo a seguir demonstra um cabeçalho Content-Type que também referencia como parâmetro o mapa de caracteres (charset):Content-type: text/html; charset=ISO-8859-1
APIs REST geralmente utilizam os parâmetros “application/json” ou “application/xml” como tipo de mídia no cabeçalho Content-Type das requisições ou respostas em HTTP/1.1. Ao encapsular os dados, a API esconde o tipo do conteúdo e fica de fora do padrão estabelecido, revelando apenas o seu formato de transferência. Enquanto o corpo da mensagem está formatado corretamente com as linguagens JSON ou XML, o conteúdo da mensagem geralmente possui semânticas que requerem processamento especial e são linguagens diferentes do JSON/XML. As aplicações clientes já aguardam por campos de dados específicos e links hipermídia formatados dentro do corpo de resposta.
Um exemplo disto é quando temos o retorno de um código HTML encapsulado em uma resposta JSON ou XML, e esse é o problema, pois uma aplicação que espera uma URI precisará, por exemplo, descobrir e tratar as tags HTML se a resposta estiver encapsulada dentro de um “Content Type” JSON/XML.
Modelo de Recurso Web
O Modelo de Recurso Web (Web Resource Model – WRM), começa com a organização hierárquica dos dados e das funções que resultam do design dos caminhos URI das APIs REST. Enquanto é verdade que REST requer as URI sendo tradadas de modo opaco, o design das URI importa muito para a galera que gosta de modelos lógicos de dados. Os esquemas de recursos web podem adicionar uma nova dimensão ao modelo de recursos provendo definições de tipos de estrutura de dados para descrever as formas representativas que são trocadas entre o cliente e o servidor.
Como por exemplo, considere a URI de uma API REST como http://api.futebol.apirest.com/jogadores/1425 que responde a uma requisição GET com a representação de um recurso Jogador que é formatado em JSON. Se o valor do cabeçalho Content-Type declara que o tipo de resposta da mídia é application/json, ele terá transmitido da maneira informada, mas sem considerar o esquema de representação do Jogador. Esse cabeçalho de resposta Content-Type simplesmente diz ao cliente que ele deve esperar por algum texto formatado em JSON.
Ao invés disso, ele deveria comunicar que o corpo contém uma representação de um Jogador que é formatado em JSON. A maioria das APIs REST modernas comunicam seu esquema através de uma documentação legível para humanos, seja hospedada em um portal ou wiki para os desenvolvedores. Essa abordagem define um sistema mais estático, aonde os donos das APIs estão encorajando os desenvolvedores das aplicações clientes a programar na mão (e ocasionalmente cometer algum erro de digitação) os detalhes dos tipos das suas APIs. Uma vez que isso foi programado manualmente nos clientes, a API REST precisa empregar e manter um sistema de versionamento para evoluir significantemente os esquemas.
Já as definições de esquemas legíveis por máquinas são preferidas porque elas podem ser carregadas dinamicamente pelo cliente, durante o desenvolvimento e execução. Algumas APIs REST modernas utilizam frameworks como o XSD (XML Schema Definition) e JSONSchema para comunicar seus esquemas em um formato legível por máquinas. Essas soluções tem duas preocupações de design que as torna desfavoráveis. Primeiro elas exigem que o conteúdo (os dados da aplicação) em um corpo de mensagem HTTP/1.1 incluam as referencias às definições de tipo, ao invés de transmitir esse tipo aonde ele pertence: o cabeçalho Content-Type. Segundo que os formatos são uma tendência, puramente visuais, entram e saem de moda. Os formatos precisam ser acopláveis, trocar um formato por outro não deve exigir uma sobrecarga do recurso no sistema web. O esquema dos nossos recursos web devem ser desacoplados de um único formato padrão. Esquemas são reflexos constantes da nossa estrutura de dados, e os formatos oferecem uma diversidade de opções nessa estrutura.
WRML
Para separar e satisfazer essas preocupações de design, o tipo de mídia “application/wrml” pode ser utilizado para comunicar ambos os Formatos e Esquemas dos dados trocados entre as APIs REST e os seus clientes. application/wrml; schema=URI; format=URI. Esse tipo de mídia pode parecer excessivo quando comparado a outros mais simples como application/json. Contudo, ele oferece uma troca que vale a pena, esse tipo de mídia comunica diretamente para os clientes bits de informações distintos e complementares sobre o conteúdo da mensagem. O WRML (Web Resource Modeling Language) oferece esse tipo de mídia “plugável” para fornecer às aplicações web ricas o acesso direto à informação estrutural e ao tipo da mensagem incorporada. Esse design reduz a necessidade da informação ser comunicada “por fora” (documentação) e depois programada manualmente pelos desenvolvedores das aplicações clientes. O exemplo abaixo mostra o tipo de mídia WRML utilizado para descrever a estrutura de um Jogador formatado em JSON.
application/wrml; schema=http://api.schemas.wrml.org/soccer/Player; format=http://api.formats.wrml.org/application/json
Os parâmetros requeridos pelo tipo de mídia application/wrml, como o schema, identificam documentos separados que detalham os formatos das estruturas (Jogador), e são independentes entre si (o valor do parâmetro do formato do tipo de mídia). WRLM é um projeto open source ativo. Para mais informações e para acompanhar seu progresso, visite wrml.org e o livro “REST API Design Rulebook”, O’Reilly Media Inc., Outubro 2011.
Traduzido de: ProgrammableWeb