API Blueprint. Um poderoso linguagem de descrição de API de alto nível para APIs da web. API Blueprint é simples e acessível a todos os envolvidos no ciclo de vida da API. Sua sintaxe é concisa ainda expressiva. Com o API Blueprint, você pode criar e prototigar APIs para serem criadas ou documentar e testar as APIs de missão crítica já implantadas. Focada na API de colaboração, o Blueprint é construído para incentivar o diálogo e a colaboração entre as partes interessadas do projeto, desenvolvedores e clientes em qualquer ponto do ciclo de vida da API. Ao mesmo tempo, as ferramentas da API Blueprint fornecem o suporte para atingir os objetivos, seja o desenvolvimento, governança ou entrega da API. API Blueprint é completamente aberto sob a licença MIT. Seu futuro é transparente e aberto. API Blueprint não precisa de um grupo de trabalho fechado. Em vez disso, ele usa o processo RFC semelhante à linguagem Rust ou aos processos de RFC da proposta de aprimoramento do Django. Em casa no GitHub O idioma da API Blueprint é reconhecido pelo GitHub. Procure o Blueprint da API no GitHub usando o idioma: consulta da API Blueprint. O tipo de mídia para API Blueprint é textvnd. apiblueprint. E a extensão de arquivo padrão é. apib. Se você usar esta extensão, seus planos no GitHub obterão sintaxe-destacados. Construído para melhor API Designs API O Blueprint é construído para encorajar melhores projetos de API por meio de abstração. O objetivo do API Blueprint é desacoplar elementos da API para permitir a modularidade enquanto encapsulam o comportamento de implementação do backend. Por exemplo, modelo seus dados primeiro usando a sintaxe de descrição de dados. Em seguida, use e reutilize os dados em seus pontos finais da API. Design-first API Blueprint é tudo sobre a filosofia design-first. Semelhante aos testes em desenvolvimento orientado por teste, o API Blueprint representa um contrato para uma API. Discutir sua API e estabelecer o contrato antes de desenvolvido tende a levar a melhores projetos de API. Uma vez que o seu modelo de API está no lugar, todos podem testar se a implementação está de acordo com as expectativas estabelecidas no contrato. Ferramentas incríveis Graças à sua ampla adoção, há uma infinidade de ferramentas criadas para API Blueprint. De várias ferramentas autônomas, como ferramentas simuladas de servidor, documentação e teste, para soluções de ciclo de vida de API completas. Consulte a seção Ferramentas para a lista. Primeiros passos Para começar com o Blueprint da API, você precisará de um editor de texto simples. Para a melhor experiência de edição, altere o destaque de sintaxe para o Markdown ou diretamente para o Blueprint da API (se suportado pelo seu editor). Depois de escrever seu primeiro modelo de API, você pode discutir o design da API com amigos e usar as ferramentas para API Blueprint. Por exemplo, para processar documentação, gerar uma simulação de seu serviço ou começar a testar sua implementação do backend. Verifique a seção de Documentação para obter recursos adicionais na sintaxe do Blueprint da API. Tutorial do Blueprint da API. Bem-vindo ao Tutorial do Blueprint da API. Este tutorial irá levá-lo através dos conceitos básicos do idioma do Blueprint da API. Vamos construir um plano de API passo a passo para um serviço chamado Enquete uma API simples, permitindo que os consumidores vejam pesquisas e votem neles. Você pode ver a versão completa do modelo usado neste tutorial para referência. Nota: API adicional Blueprint Resources API Blueprint O primeiro passo para criar um modelo é especificar o nome da API e os metadados. Este passo é o seguinte: o plano começa com uma seção de metadados. Nesse caso, especificamos que FORMAT tem o valor de 1A. A palavra-chave de formato indica a versão do Blueprint da API. API Nome amplificador Descrição O primeiro título no modelo serve como o nome da sua API, que neste caso são Enquetes. Os títulos começam com um ou mais símbolos seguidos por um título. O Nome da API aqui usa um hash para distingui-lo como o primeiro nível. O número de você usará determinará o nível do título. Seguir o título é uma descrição da API. Você pode usar outros títulos para interromper a seção de descrição. Grupos de recursos Agora é hora de começar a documentar os recursos da API. Usando a palavra-chave Grupo no início de um título, criamos um grupo de recursos relacionados. Dentro do grupo de recursos de perguntas, temos um recurso chamado Coleção de Perguntas. Este recurso permite visualizar uma lista de perguntas. O cabeçalho especifica o URI usado para acessar o recurso dentro de colchetes no final do cabeçalho. O Blueprint da API permite que você especifique cada ação que você pode fazer em um recurso. Uma ação é especificada com um subtítulo dentro de um recurso com o nome da ação seguido pelo método HTTP. Uma ação deve incluir pelo menos uma resposta do servidor, que deve incluir um código de status e pode conter um corpo. Uma resposta é definida como um item de lista dentro de uma ação. As listas são criadas pelos itens da lista anterior com um. Ou -. Esta ação retorna um código de status 200 juntamente com um corpo JSON. Nota: Especificar o tipo de mídia após o código de status da resposta gerar um cabeçalho HTTP de Tipo de Conteúdo. Não é necessário especificar explicitamente o cabeçalho Content-Type. O recurso de pesquisa tem uma segunda ação que permite que você crie uma nova pergunta. Esta ação inclui uma descrição que mostra a estrutura que você enviaria para o servidor para executar esta ação. Esta ação requer uma carga útil JSON como parte da solicitação da seguinte maneira: Este exemplo retorna um código de status 201, juntamente com cabeçalhos HTTP e um corpo. O próximo recurso é Question, que representa uma única pergunta. Modelo URI O URI para o recurso Question usa um componente variável, expresso pelo modelo URI. Neste caso, existe uma variável ID chamada questionista. Representado no modelo URI como. Parâmetros URI Os parâmetros URI devem descrever o URI usando uma lista de Parâmetros. Para Pergunta seria a seguinte: A variável questionid do modelo URI é um parâmetro para cada ação neste recurso. É definido aqui usando um número de tipo arbitrário. Seguido de uma descrição para o parâmetro. Consulte a Seção de Parâmetros URI da Especificação Blueprint da API para obter mais exemplos. Este recurso tem uma ação para recuperar o detalhe das perguntas. Resposta sem um corpo Este recurso tem uma ação de exclusão. O servidor retornará uma resposta sem um corpo. Complete Blueprint Você pode encontrar uma implementação desta API em polls. apiblueprint. org juntamente com o completo Blueprint API da Enquete no repositório API Blueprint Examples. Você também pode apreciá-lo em Apiary. Nota: Dê uma olhada no Glossário de Termos da API, se precisar de alguns dos termos usados nesse documento. API Blueprint Tools Visite a seção Tooling de apiblueprint. org para encontrar ferramentas para usar com os Blueprint do API.
No comments:
Post a Comment