Um guia para a REST e o design de API

Se a nica ferramenta que voc tem for um martelo...

Em seu livro de 1966, "The Psychology of Science", o psiclogo Abraham Maslow defendeu a ideia de que no campo da psicologia o tratamento deve ser abordado de vrias perspectivas para se obter novas ideias e no apenas continuar a usar as mesmas teorias e tcnicas criadas por Freud e seus seguidores h tantos anos. Reconhecendo que pode ser difcil alterar um ponto de vista, Maslow escreveu: "Se voc s tem um martelo, tentador tratar tudo como um prego". Todos ns j tivemos essa experincia. Estamos to acostumados com a maneira como as coisas eram feitas no passado, que algumas vezes no questionamos as razes de faz-las.

Essa referncia psicologia em um trabalho sobre REST e Design de API pode ser curiosa, mas ela ajuda a ilustrar dois pontos distintos: (1) que todas as decises de design, seja no software ou na arquitetura, devem ser feitas dentro do contexto de requisitos funcionais, comportamentais esociais, no de tendncias aleatrias; (2)quando voc sabe fazer bem apenas umacoisa, tudo tende a parecer idntico.

Em sua tese,"Estilos arquitetnicos eodesign de arquiteturas de software combase na rede"1, Roy Fielding define aREST (Representational State Transfer - Transferncia de estado representacional): "Com frequncia, vemos projetos de software comearem com a adoo da ltima onda em design arquitetnico e s mais tarde que se descobre se os requisitos do sistema requerem ou no essa arquitetura."

No tem tempo para ler toda a tese de Fielding? No tem problema. Criamos esta viso geral de alto nvel especialmente para voc. Para comear, vamos examinar a REST detalhadamente.

02

"Se a nica ferramenta que voc tem for um martelo, tudo parece ser um prego." Abraham Maslow, The Psychology of Science

1 Estilos arquitetnicos e o design de arquiteturas de software com base na rede

03

Estilo versus padro

Um estilo arquitetnico uma abstrao, no algo concreto. Por exemplo, observe uma catedral gtica. A catedral diferente do estilo arquitetnico gtico. O estilo gtico define os atributos ou as caractersticas que voc vemuma catedral construda naquele estilo.

Em comparao, o NIST (National Institute of Standards - Instituto nacional depadres dos EUA) e o NEC (National Electrical Codes - Cdigos eltricos nacionais dos EUA) so rgos governamentais que produzem regras que reconhecemos como padres. Se a parte eltrica da construo for feita incorretamente, o lugar pode queimar completamente. As pessoas geralmente confundem padres, dos quais sabemos o que certo ou errado, e estilos, ummodo especfico de expresso.

Na internet, a REST um estilo, e o HTTP um padro. A REST conta com protocolos de comunicao sem estado, que podem ser armazenados em cache, como o HTTP, para facilitar o desenvolvimento de aplicativos. Aplicando os princpios do design da REST a um protocolo, como o HTTP, os desenvolvedores podem criar interfaces que podem ser usadas a partir de praticamente qualquer dispositivo ou sistema operacional.

Qual o seu estilo?

Os trs estilos comuns da arquitetura da web so:

Encapsulamento (protocolo SOAP)

Objetos (CRUD (Create/Read/Update/Delete - Criar/Ler/Atualizar/Excluir))

Hipermdia (REST)

Assista a este vdeo2 para compreender os recursos principais dos estilos arquitetnicos comuns edecidir qual deles atende melhor s suas necessidades.

2 Design de APIs, Lio 201: Estilos arquitetnicos de APIs da web, Academia de API

04

Os estilos so descritos pelas restries Um estilo arquitetnico descrito pelos recursos que tornam uma construo ou outra estrutura notvel e identificvel. As formas caractersticas da arquitetura gtica, por exemplo, incluem oarco ogival, a abboda de arcos cruzados, colunas, torres, pinculos e fachadas decoradas.

De maneira semelhante, a REST descrita por um conjunto de restries arquitetnicas que tentam minimizar alatncia e as comunicaes em rede e, ao mesmo tempo, maximizam a independncia e a escalabilidade deimplementaes de componentes. As seis restries da REST incluem:1. Cliente/servidor requer que um servio oferea uma ou mais operaes e que os servios esperem

queosclientes solicitem essas operaes. 2. Sem estado exige que a comunicao entre o consumidor do servio (cliente) e o provedor do servio

(servidor) seja sem estado. 3. Cache exige que as respostas sejam rotuladas claramente como armazenveis em cache ou no

armazenveis em cache. 4. Interface uniforme exige que todos os provedores e consumidores de servio em uma arquitetura

compatvel com a REST compartilhem uma nica interface do usurio para todas as operaes. 5. Sistema em camadas exige a habilidade de adicionar ou remover intermedirios em tempo de execuo

sem interromper o sistema. 6. Codificao sob demanda (opcional) permite que a lgica em clientes (como navegadores da web) seja

atualizada independentemente da lgica do servidor usando cdigo executvel fornecido de provedores de servios para consumidores.

"Esta uma das poucas chaves efetivas para oproblema dodesign ahabilidade dodesigner dereconhecer omximo de restries possvel seu desejo e entusiasmo de trabalhar com essas restries. Restries de preo, tamanho, potncia, equilbrio, superfcie, tempo e assim por diante."3

Charles Eames, Eames Design.Vrias organizaes

Replicadas

Por demanda

RR CS

CSS$ LSS COD

LS VM U

RESTLCODC$SSLC$SSC$SS

Sem estado

Confivel

Separadas

Em ca-madas Programvel

Interface uniforme

Simples

Visvel

Processamento intermedirio

Compartilhado

Mvel

Extensvel Reutilizvel

ExpansvelArmazenvel em cache

Figura: Derivao da REST por restries de estilos

3 http://www.eamesoffice.com/the-work/design-q-a-text/

05

Conector componente De acordo com Fielding, "a [REST] obtida colocando as restries na semntica do conector onde outros estilos se concentraram na semntica do componente". O design de Fielding focaliza a restrio na maneira como as coisas se conectam umas com as outras, no na maneira como elas funcionam internamente, e ele aplica essa teoria a toda arede. Ao criar aplicativos em grande escala, o conceito de que o conector no igual ao componente sempre negligenciado. Mas Fielding traz o conceito para o primeiro plano.

Os componentes funcionam de maneiras exclusivas para resolver problemas. O MySQL funciona demaneira diferente do SQL Server, assim como o CouchDB ou o MongoDB. O mesmo pode ser dito sobre sistemas de arquivos que tm como base o UNIX, o Windows ou o Mac. A maneira como voc coloca informaes na fila e a maneira como voc decide quando comea e quando termina uma transao so recursos locais do componente que podem ser manipulados pelo desenvolvedor. Elesso componentes do desenvolvedor, seu sistema operacional, ferramentas e linguagem, e so, portanto, privados.

Por outro lado, os conectores so pblicos. Os conectores so uma srie de pipes padronizados com osquais todos os desenvolvedores trabalham. Com base no princpio de Fielding, os desenvolvedores podem ser to criativos ou mundanos quanto desejarem dentro de seus componentes privados, desde que concordem em receber e enviar informaes usando conectores pblicos padronizados.

Esses diferem dos conectores que incluem:

Servidores web Agentes de navegador Servidores proxy Cache compartilhado

Quais so os componentes? Eles incluem:

Bancos de dados Sistemas de arquivos Filas de mensagens Ferramentas de gerenciamento

de transaes Cdigo-fonte

Mantenha os componentes eos conectores separados, facilitando seu intercmbio mais tarde. Por exemplo, ocdigo que voc escreve para seu servidor web criado para falar com muitos dispositivos na internet pblica. Mas, ocdigo que voc escreve para seus componentes criado para falar especificamente com as ferramentas que esto disponveis para voc.

06

Garantindo que os conectores funcionem em conjunto Ao criar aplicativos com base no cliente ou servios no servidor, o que torna o desenvolvimento desafiante e empolgante acorrespondncia dos componentes privados com os conectores pblicos, conectando-os e encadeando-os. Como voc garante que um conector funcione? Como criar aplicativos expansveis se eles esto se comunicando por meio de conectores?

Identificao de recursos URIs, URLs e URNs como

identificadores

Representaes de recursos

tipos de mdia como maneiras de representar

informaes transmitidas entre partes

Mensagens autodescritivas

combinando metadados em cabealhos, bem como

ocorpo de uma mensagem, para criar uma resposta

autodescritiva

Hipermdia links e formulrios como

uma maneira de descrever para o cliente as aes

disponveis que so suportadas atualmente

peloservio

A restrio da interface uniforme fundamental para a criao de qualquer servio REST. Ela simplifica e separa os conectores, o que permite que cada parte evolua de maneira independente. Por causa da maneira como a web usada atualmente, as quatro restries acima so as ferramentas essenciais que ajudam os desenvolvedores a obter a interface uniforme de Fielding. As prximas pginas explicam essas ferramentas mais profundamente.

07

URIs para identificao

Como a RFC23964 descreve, "um URI (Uniform Resource Identifier) uma cadeia de caracteres compacta para identificar um recurso abstrato ou fsico". Esse identificador pode ser obtido de duas maneiras, uma URL (Uniform Resource Locator) ou um URN (Uniform Resouce Name). As URLs (por exemplo, http://example.org/users/mike) so usadas para identificar o local online de um recurso individual, enquanto os URNs (por exemplo, urn:user:mike) so identificadores persistentes independentes de local. O URN funciona como o nome de uma pessoa, e uma URL semelhante ao endereo dessa pessoa. Ou seja, o URN define a identidade de um item ("o nome do usurio mike"), e a URL fornece um mtodo delocaliz-lo ("mike pode ser localizado em example.org/users/").

Os componentes de um URI incluem: Nome do esquema identifica o protocolo (por exemplo, FTP:, HTTP:, HTTPS:, IRC:)

Parte hierrquica destinada a manter informaes hierrquicas por natureza Autoridade refere-se resoluo real do DNS do servidor (por exemplo, o nome do domnio ou o endereo IP) Caminho refere-se a uma sequncia de segmentos separados por uma barra ("/")

Consulta contm informaes adicionais que no so hierrquicas por natureza e geralmente so separadas por um ponto de interrogao ("?")

Fragmento fornece direo para um recurso secundrio dentro do primrio identificado pela Autoridade e o Caminho separados do restante por um ("#")

Estrutura dos URIs

esquema autoridadeautoridade caminho consulta fragmento

URL:

URN:

foo://example.com:8042/over/there?name=ferret#nose

urn:example:animal:ferret:nose

4 https://tools.ietf.org/html/rfc2396

0908

Tipos de mdia para representao De acordo com a RFC20465, os identificadores do tipo MIME (tipos de mdia) devem ser usados para "especificar a natureza dos dados no corpo de uma entidade MIME, junto com quaisquer informaes auxiliares que possam ser necessrias". Os tipos MIME foram usados primeiro para transmisses de email, como evidenciado por seunome completo: Multipurpose Internet Mail Extensions. Atualmente, os tipos MIME permitem que as pessoas troquem diferentes tipos de dados pela internet: udio, vdeo, texto, imagens e programas de aplicativos.

Os tipos MIME (ou tipos de mdia) identificam a natureza dos dados e as informaes auxiliares. Na web, ostipos de mdia tambm identificam regras de processamento para a mensagem. A cadeia de caracteres doidentificador do tipo MIME tem um tipo e um subtipo separados por uma barra (por exemplo, texto/simples, imagem/gif etc.).

Alm das cadeias de caracteres do tipo MIME padro (por exemplo, aplicativo/json), os identificadores podemser criados usando as seguintes convenes:

Use vnd. como um prefixo para o subtipo dos tipos MIME especficos ao fornecedor que fazem parte deum produto comercial (por exemplo, vnd.bigcompany.report/json).

Use prs. como um prefixo para o subtipo de tipos MIME pessoais/personalizados que no fazem parte deum produto comercial (por exemplo, prs.smith.data/json).

Registro do tipo MIME Uma lista completa dos tipos MIME oficiais atribudos pela IANA (Internet Assigned Number Authority - Autoridade para Atribuio de Nmeros daInternet) pode serencontrada aqui.

5 https://tools.ietf.org/html/rfc2396

09

Cabealhos+corpo para mensagens autodescritivasA RFC26166 declara que [no HTTP] as mensagens consistem em uma linha de incio, zero ou mais campos de cabealho (tambm conhecidos como "header"), uma linha vazia (por exemplo, uma linha com nada antes do CRFL) indicando o final dos campos de cabealho e possivelmente um corpo da mensagem.

Cada solicitao de cliente e resposta de servidor uma mensagem, e os aplicativos compatveis com aREST esperam que cada mensagem seja autodescritiva. Isso significa que cada mensagem deve conter todas as informaes necessrias para concluir a tarefa. Outras maneiras de descrever esse tipo de mensagem so "sem estado" ou "sem contexto". Cada mensagem passada entre o cliente e o servidor pode ter um corpo e metadados.

As implementaes da REST tambm dependem da noo de um conjunto restrito de operaes que so totalmente compreendidas pelo cliente e pelo servidor no incio. No HTTP, as operaes so descritas na "linha de incio", e as seis operaes mais amplamente usadas no HTTP so:

GET retorna qualquer informao identificada pelo URI de solicitao

HEAD idntica ao GET, exceto que o servidor no precisa retornar um corpo de mensagem na resposta, apenas os metadados

OPTIONS retorna informaes sobre as opes da comunicao disponveis na cadeia de solicitao/resposta identificada pelo URI de solicitao

PUT solicita que a entidade embutida seja armazenada sob o URI de solicitao fornecido

POST solicita que o servidor de origem aceite a entidade embutida na solicitao como um novo subordinado do recurso identificado pelo URI de solicitao

DELETE solicita que o servidor de origem exclua o recurso identificado pelo URI de solicitao

As trs primeiras so operaes somente leitura, enquanto as trs ltimas so operaes de gravao. No HTTP, h regras bem-definidas de como se espera que os clientes e os servidores se comportem ao usar esses operadores. Os nomes e os significados dos elementos que acompanham os metadados (cabealhos) tambm so bem-definidos. Os aplicativos compatveis com a REST que executam por HTTP compreendem e seguem essas regras muito cuidadosamente.

Exemplo de troca de "GET" via HTTP

Para recuperar um arquivo em http://www.somehost.com/path/file.html, abra um soquete para o host www.somehost.com, use a porta padro 80, porque nenhuma est especificada na URL, e envie o seguinte pelo soquete:

GET/path/file.html HTTP/1.0

From: someuser@jmarshall.com

User-Agent: HTTPTool/1.0

[linha em branco aqui]

Enviado de volta pelo mesmo soquete, oservidor deve responder com:

HTTP/1.0 200 OKDate: Fri, 31 Dec 1999 23:59:59 GMTContent-Type: text/htmlContent-Length: 1354

Feliz Ano Novo!

(mais contedo do arquivo)

6 https://tools.ietf.org/html/rfc2396

10

Links e formulrios para hipermdia Fatores HAo comparar tipos de mdia, pode ser til documentar os Fatores H existentes em um grfico visual simples. Noexemplo a seguir, a linha inferior identifica fatores bsicos de link osfatores de hipermdia mais notveis enquanto as duas linhas superiores identificam fatores de dados decontrole.

Fatores de hipermdia

HTML

Suporte de links[LE] Links embutidos[LO] Links de sada[LT] Consultas modeladas[LN] Atualizaes no idempotentes[LI] Atualizaes idempotentes

Suporte de dados de controle[CR] Dados de controle para solicitaes de leitura[CU] Dados de controle para solicitaes de atualizao[CM] Dados de controle para mtodos dainterface[CL] Dados de controle para links

Para obter mais informaes sobre Fatores H: http://amundsen.com/hypermedia/hfactor/.

CL

CR

LE

CU

LO

CM

LT LN LI

Links e formulrios so usados em um tipo de mdia para oferecer suporte restrio dehipermdia de Fielding. Por exemplo, h inmeras funcionalidades no HTML, eonavegador web comum compreende as regras para todas elas. Os links e formulrios em uma mensagem HTML so fceis de reconhecer, mas o que pode no ser to claro so as regras de processamento ou as semnticas que esto associadas a eles.

Os links e formulrios do a voc a habilidade de executar uma ao. Eles so funcionalidades. O HTML tem um conjunto bem-definido de funcionalidades. Algumas funcionalidades permitem que voc grave dados, como um formulrio que tenha a propriedade de mtodo definida como "POST." Algumas funcionalidades permitem que voc extraia dados de um local remoto para exibir dentro do documento HTML atual, com o elemento IMG. Oelemento A do HTML uma funcionalidade para navegao para um novo local na web.

De acordo com Fielding, "a hipermdia definida pela presena de informaes de controle do aplicativo embutidas dentro da apresentao das informaes ou em uma camada acima". Para Fielding, a REST oferece aos provedores de servio a habilidade de enviar informaes de controle (links e formulrios) a aplicativos decliente de todo o mundo enviando funcionalidades, que so os controles de hipermdia.

Software que amplia o tempo de vida A arquitetura fsica de qualidade amplia os tempos de vida. Prdios que foram construdos h centenas de anos podem ser to cheios de vida, to teis, to vibrantes e confortveis hoje como eram quando as pessoas entraram neles pela primeira vez, at mesmo quando esses prdios so transformados em museus ou sales de reunio em prdios de apartamentos. Por qu? Porque esses prdios atemporais contam com padres arquitetnicos universais que atravessam o tempo e o espao. Uma entrada uma entrada, uma janela uma janela. A maneira como esses elementos so implementados depende dos materiais disponveis. A maneira como eles so representados diferente em cada caso local, mas eles ainda podem ser identificados ano aps ano.

No desenvolvimento de software, o conceito o mesmo. Algumas vezes, os arquitetos e desenvolvedores desoftware desejam criar aplicativos que durem por um longo tempo. A REST, com seu conjunto de restries universais (como padres arquitetnicos), uma maneira de conseguir isso.

Mas Fielding no disse que essa a nica maneira de obter xito. Quando ele escreveu sua tese, no incluiu todas as possibilidades, nem todas as respostas. Na verdade, muitas partes foram deixadas inacabadas. O que Fielding fez, no entanto, foi documentar sua abordagem de criar um estilo arquitetnico para software em rede que era baseado na identificao de uma srie de restries para atingir seu objetivo de minimizar a latncia emaximizar a escalabilidade. Na verdade, ele usou restries da mesma maneira como Charles Eames as usou, porque elas ajudaram a atingir seu objetivo.

Podemos tirar proveito da experincia de Fielding para nos ajudar a ver as coisas demaneira um pouco diferente. Podemos usar as ferramentas que ele forneceu para experimentar com restries e expressar nosso prprio estilo e, no processo, criar aplicativos de software notveis que podem, se desejarmos, resistir ao teste do tempo.

11

"O valor de um objeto bem-criado quando ele tem um conjunto to rico de funcionalidades que as pessoas que o usam podem fazer coisas que odesigner nunca imaginou."7

Donald Norman, 1994

7 https://www.youtube.com/watch?v=NK1Zb_5VxuM

A CA Technologies (NASDAQ: CA) cria software que acelera a transformao das empresas e permite que elas aproveitem as oportunidades da economia dos aplicativos. O software est no cerne de todas as empresas, em todos os setores. Doplanejamento ao desenvolvimento e do gerenciamento segurana, a CA est trabalhando com empresas de todo o mundo para mudar a maneira como vivemos, fazemos negcios e nos comunicamos usando dispositivos mveis, as nuvens privada e pblica e os ambientes distribudos e de mainframe. Obtenha mais informaes em ca.com/br.

Copyright CA 2015. Todos os direitos reservados. Este documento apenas para fins informativos e no representa nenhum tipo de garantia. Todas as marcas comerciais, nomes de marcas, marcas de servio e logotipos aqui mencionados pertencem s suas respectivas empresas.

CS200-110010

Saiba mais sobre o CA API ManagementVisite ca.com/br/API