Design de API

Passando dos requisitos para uma API

Como a maioria das tecnologias, uma API é uma solução para um problema. Para projetar a API certa, você precisa garantir que o problema que está abordando seja claramente definido, respondendo às seguintes perguntas:

• Quem são os consumidores-alvo desta API?
• Que tipo de informação os consumidores manipularão por meio da API?
• Que ações os consumidores executarão na API?

Por exemplo, se você é uma empresa de entrega de comida, pode querer criar uma API para sua rede de parceiros que lhes permita navegar e pesquisar em um banco de dados de restaurantes para os quais você oferece serviço de entrega.

Neste exemplo, sua API está direcionada aos parceiros da sua empresa. Eles precisarão manipular dados sobre restaurantes e realizar buscas nesses dados, com determinadas opções de filtragem e classificação.

Outro exemplo: se você é uma empresa de SaaS de calendário, pode querer criar uma API para que outros desenvolvedores de front-end ao redor do mundo possam criar novos aplicativos móveis e da Web baseados no seu sistema de calendário.

Pensar nos consumidores da sua API é o primeiro passo para proporcionar a eles uma boa experiência de desenvolvimento. Isso ajudará sua API a se destacar e aumentar os níveis de engajamento.

Os elementos que compõem uma API

Existem quatro conceitos-chave usados ao projetar uma API:

• Um Recurso é um elemento com o qual seus consumidores interagirão através da sua API. Os recursos são identificados de forma exclusiva por um caminho, que, combinado com o endpoint da API, fornece um endereço exclusivo para um recurso na Web. Por exemplo, Calendários é o nome de um recurso que corresponde a uma lista de calendários, e seu caminho é /calendars.
• Uma Operação é a ação que pode ser realizada em seus recursos. As operações mais comuns são GET (ler), POST (criar), PUT (atualizar) e DELETE. Por exemplo, Listar todos os calendários é o nome de uma operação que usa o método GET no recurso Calendários.
• Um Tipo de dados é uma descrição dos dados reais que são trocados pela rede. Por exemplo, Calendário é o nome de um tipo de dados que descreverá todas as propriedades de um Calendário, como seu nome, proprietário e uma referência aos eventos que pertencem a ele. A operação Listar todos os calendários retorna uma lista de tipos de dados Calendário.
• Um Componente é um elemento que pode ser reutilizado em toda a definição da API. Por exemplo, se você precisar usar o mesmo parâmetro de consulta em várias operações, poderá criá-lo como um componente e referenciá-lo em quantas operações forem necessárias.

Existem outros elementos úteis que compõem uma API:

• Um Endpoint é o principal ponto de entrada para sua API na Web. Um endpoint é composto por um esquema como HTTPS e um host como www.calendar-api.com.
• Um bloco de Texto pode ser usado para inserir livremente qualquer texto (incluindo markdown) que pode ser colocado em qualquer lugar no design da sua API. Use blocos de texto para explicar tópicos transversais como autenticação e tratamento de erros.
• Uma Seção é usada para agrupar significativamente recursos e tipos de dados. Use-os para tornar o design da sua API mais claro e amigável para desenvolvedores. Você pode arrastar e soltar elementos em seções no painel esquerdo, e também pode reordenar as seções entre si.

No API Designer, você poderá criar esses elementos no menu Criar novo no canto superior direito.

As URLs de servidor são criadas na tela de informações gerais. Uma URL de servidor pode ser Publicada ou Não publicada. Se for publicada, ela aparecerá na Documentação ao vivo.