Noções básicas de desenvolvimento de APIs REST e RESTful

Desenvolvedores da Web estão freqüentemente falando sobre Princípios REST e arquitetura de dados RESTful, como é um aspecto crucial do desenvolvimento moderno, mas às vezes pode ser incrivelmente confuso. REST não é uma tecnologia em si, mas sim um método de criação de APIs com determinados princípios organizacionais. Esses princípios servem para orientar os desenvolvedores e criar um ambiente mais universal para o processamento de solicitações de API.

Neste post, gostaria de explicar as práticas de desenvolvimento RESTful a partir de uma visão panorâmica. Eu quero atacar a que em vez do como. Embora eu toque em ambas as áreas, este post é feito para qualquer um que esteja no desenvolvimento web, mas simplesmente não consegue entender o conceito de APIs REST.

REST para desenvolvedores da Web

A sigla REST significa Transferência de Estado Representacional. Isso pode parecer um pouco confuso, e a entrada do wiki faz com que pareça ainda mais confuso. Mas é possível simplificar a terminologia.

REST é apenas uma série de diretrizes e estilos arquitetônicos usados ​​para transmissão de dados. É comumente aplicado a aplicativos da Web, mas também pode transmitir dados para o software.

A sigla API significa Application Programming Interface, que são métodos de conectando-se com outras bibliotecas ou aplicativos. O Windows tem várias APIs e o Twitter também tem uma API da Web, embora elas executem tarefas diferentes com objetivos diferentes.

Combinando tudo isso, as APIs RESTful são APIs que seguem a arquitetura REST.

O que exatamente é a arquitetura REST?

É aí que é difícil estabelecer detalhes. No entanto, existem algumas constantes arquiteturais, como:

• Consistência em toda a API
• Existência sem estado, ou seja, sem sessões do lado do servidor
• Uso de Códigos de status HTTP onde apropriado
• Uso de Pontos de extremidade de URL com uma hierarquia lógica
• Versão no URL em vez de cabeçalhos HTTP

Não há diretrizes excessivamente específicas, como a especificação HTML5 do W3C, o que poderia causar confusão e um miasma de incerteza em torno da terminologia REST.

Além disso, a lista acima não deve ser considerado regras rígidas e rápidas, mesmo que sejam verdadeiras APIs RESTful mais modernas.

REST é um metodologia leve o que o torna perfeito para dados HTTP. É por isso que o REST se tornou tão popular na Web e por que é amplamente considerado como a melhor escolha para o desenvolvimento de APIs..

Como diz Vinay Sahni, “uma API é uma interface do desenvolvedor.” Tudo deve ser fácil de usar e fornecer uma ótima experiência ao usuário. APIs RESTful têm como objetivo fazer exatamente isso.

Principais dicas para APIs RESTful

Essas dicas estão no contexto das APIs estritamente para aplicações web. Isso significa que HTTP é um requisito, e isso geralmente significa que os dados da API estão hospedados em um servidor externo. Vamos examinar como as APIs RESTful funcionam no lado do usuário da API.

O usuário da API é o desenvolvedor da Web que pode criar um script que se conecta a um servidor de API externo e, em seguida, os dados necessários são transmitidos pelo HTTP. O desenvolvedor pode exibir dados em seu site sem ter acesso pessoal ao servidor externo (como puxar dados do Twitter).

De um modo geral, existem quatro comandos costumava acessar APIs RESTful:

1. PEGUE para recuperar um objeto
2. POSTAR para criar um novo objeto
3. COLOCAR para modificar ou substituir um objeto
4. EXCLUIR para remover um objeto

Cada um desses métodos deve ser passou com a chamada da API dizer ao servidor o que fazer.

A grande maioria das APIs da web apenas permitir PEGUE solicitações de para extrair dados de um servidor externo. Autenticação é opcional, mas certamente uma boa idéia ao permitir comandos potencialmente danosos como COLOCAR ou EXCLUIR.

No entanto, muitas APIs RESTful não chegam tão longe. Considere o Pokéapi, que é um banco de dados gratuito da API Pokémon. É aberto ao público com limitação de taxa decente (limitando os usuários a um determinado número de solicitações de API durante um período de tempo), mas apenas permite PEGUE método para acessar recursos. Isso pode ser coloquialmente denominado API somente de consumo.

Tipos de retorno também são importantes e devem manter a homogeneidade para todos os recursos. JSON é um tipo de retorno popular com especificações online que explicam estruturas de dados adequadas.

Uso de APIs RESTful substantivos para objetos da API, e verbos para executar ações nesses objetos. Autenticação pode fazer parte disso, limitar a taxa também pode ser parte disso. Mas uma API muito simples pode passar sem muita preocupação com as limitações do usuário.

Acessando recursos da API

APIs públicas são normalmente acessível a partir de endereços diretos do site. Isso significa a estrutura da URL é importante, e deve ser usado apenas para solicitações de API.

Alguns URLs podem incluir um diretório de prefixo como / v2 / para uma versão atualizada 2 de uma API anterior. Isso é comum para desenvolvedores que não querem depreciar sua API 1.x, mas ainda querem oferecer a mais nova estrutura.

Eu realmente gostei deste post cobrindo estruturas básicas de URL e exemplos de outros serviços.

Observe que o endpoint os dados de retorno serão alterados dramaticamente baseado no Método HTTP. Por exemplo, PEGUE recupera conteúdo, enquanto POSTAR cria novo conteúdo. O pedido pode apontar para o mesmo ponto final, mas o resultado pode ser muito diferente.

Examinar os exemplos on-line pode ajudar você a entender os conceitos de forma mais clara. Nós já vimos o Pokeapi, mas aqui estão alguns outros exemplos de API do mundo real para folhear:

• API do Reddit
• API do GitHub
• API do Flickr
• API do Pinterest

Construindo sua própria API

O processo de construção de sua própria API não deve ser ignorado, mas também não é tão complicado quanto você imagina. Isso leva um Compreensão dos padrões de design da API e das práticas recomendadas para construir algo de valor real.

Cada API deve conectar ao seu servidor para retornar dados de algum tipo. Você não precisa apenas escrever código para fazer isso, mas também precisa formatar os dados de retorno. Outros requisitos em potencial incluem autenticação e limitação de taxa, então construir uma API certamente não é para os fracos de coração.

Mas vamos dar uma olhada alguns princípios básicos da arquitetura da API.

Construir Endpoints

Um aspecto do desenvolvimento da API é pontos finais do edifício. Quando criando recursos você quer usar substantivos, não verbos. Isso significa que os dados da API devem retornar uma pessoa, um lugar ou outra coisa. uma coisa com atributos específicos (por exemplo, um tweet e todos os seus metadados).

Pode ser difícil aprender a nomear substantivos, mas esse é um aspecto crucial do desenvolvimento da API. A simplificação é melhor sempre que possível.

Um grande debate é singular versus plural substantivos. Se você cria uma API do Twitter, pode ter o grupo de objetos primeiro (ou seja, tweet), depois o segundo item do objeto (ou seja, ID do tweet).

 $ / tweet / 15032934882934 $ / tweets / 15032934882934 

Neste caso, eu diria que a forma singular parece melhor. Isso é verdade especialmente quando apenas um recurso está sendo retornado. Mas não há uma resposta correta 100% documentada, então faça o que melhor se encaixa no seu projeto.

Definir o tipo de retorno

Outra consideração é dados do tipo de retorno. A maioria dos usuários da web espera por conteúdo JSON, então essa é provavelmente a melhor opção. O XML é outra opção se você quiser oferecer ambos. No entanto, JSON é o tipo de retorno da API fundamental entre os desenvolvedores da Web.

Há muito mais no desenvolvimento de APIs, por isso recomendo jogar primeiro com APIs. Dessa forma, você pode ver como outros desenvolvedores criam suas APIs e, com sorte, você se familiarizará com os requisitos típicos.

Se você está apenas começando, por favor, considere skimming estes dev tutorials:

• Site de Tutorial da API REST
• Escrevendo uma API REST simples
• Criando um serviço da Web RESTful

Mais recursos

A melhor maneira de aprender o desenvolvimento de aplicativos da Web é através da prática. Teoria concedida é sempre vale a pena estudar, porque permite conversar com os desenvolvedores e entender como as coisas funcionam.

Mas um bom lugar para começar com o desenvolvimento da API é conectando-se a outras APIs primeiro. Aprenda os fundamentos das conexões do lado do cliente e, a partir daí, você pode migrar para o desenvolvimento de API do lado do servidor, criando sua própria API a partir do zero.

Se esse é o seu objetivo, considere os seguintes recursos para ajudar ao longo de sua jornada.

Livros

• Guia de Design REST API
• APIs da Web RESTful
• Cookbook de serviços Web RESTful
• Resto não perturbado: um guia para projetar a API perfeita

Artigos

• Um guia para iniciantes em HTTP e REST
• Criando uma API RESTful
• Guia de nomenclatura de recursos RESTful
• Criando uma API REST usando a pilha MEAN