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.

"Se a nica ferramenta que voc tem for um

martelo, tudo parece ser um prego."
Abraham Maslow, The Psychology of Science

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

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

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.

03

Design de APIs, Lio 201: Estilos arquitetnicos de APIs da web,

Academia de API

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.
Figura: Derivao da REST por restries de estilos
Replicadas
RR

CS
Sem estado

Por demanda
$

das
epara

Em camadas

Process
amento
interme
dirio

CSS

C$SS

ram
vel

Expansvel

LC$SS

VM

Mvel

LSS
Compartilhado

Confivel
Armazenvel
em cache

LS

Interface uniforme

Prog

Simples
COD

Extensvel

Visvel
Reutilizvel

LCODC$SS
Vrias organizaes

REST

"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.
3

04

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

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.
Quais so os componentes?
Eles incluem:

Esses diferem dos conectores

que incluem:

Bancos de dados
Sistemas de arquivos
Filas de mensagens
Ferramentas de gerenciamento
de transaes
Cdigo-fonte

Servidores web
Agentes de navegador
Servidores proxy
Cache compartilhado

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.

05

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.

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.
06

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

URL:

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

URN:
4

autoridade

caminho

urn:example:animal:ferret:nose

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

07

consulta

fragmento

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).

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

08
09

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.

Cabealhos+corpo para mensagens

autodescritivas
A 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

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:

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

HTTP/1.0 200 OK
Date: Fri, 31 Dec 1999 23:59:59 GMT
Content-Type: text/html
Content-Length: 1354

OPTIONS retorna informaes sobre as opes da comunicao disponveis na cadeia de solicitao/

resposta identificada pelo URI de solicitao

<html>

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

<h1>Feliz Ano Novo!</h1>

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.
6

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

09

<body>

(mais contedo do arquivo)

</body>
</html>

Links e formulrios para hipermdia

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.

Fatores H
Ao 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

CL
CR CU CM
LE LO

LT LN

LI

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/.

10

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.

"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

11

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

Saiba mais sobre o CA API Management

Visite ca.com/br/API

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