Adaptado de Nordic APIs

Enquanto é extremamente importante prover uma experiência de desenvolvedor de qualidade, isso não significa apenas um bom design de API e uma documentação bem escrita. Um dos elementos mais importantes de uma experiência de desenvolvedor de sucesso é o SDK.Para desenvolvedores de aplicações, um SDK é constantemente o ponto de entrada para elementos na API. Cada API “forkada”, cada função secundária, cada funcionalidade B2B pode ser dirigida pelo SDK e suas funções. Ter uma experiência de desenvolvedor ruim para SDKs é semelhante a envenenar a raiz de uma árvore frutífera: mesmo que prospere, suas frutas podem vir envenenadas (ou muito amargas).Mas como fazer o ecossistema do SDK o mais forte possível? Voltando à analogia da árvore, devemos tornar nossas raízes saudáveis, robustas e poderosas. Trouxe aqui algumas práticas para construir uma boa SDK, e por meio disso, formar uma rede de APIs robusta.

SDK: O que é?

Antes de apresentar dicas de como construir a SDK, a definição de SDK deve ser apresentada. De maneira simplificada, um SDK é um Software Developer Kit que inclui todas as informações e peças necessárias para criar uma aplicação específica. Nesse caso, uma SDK para uma API inclui todas as informações e peças necessárias para criar uma aplicação que a utiliza. Em resumo, atua como um sistema de guia para integração.Idealmente, uma SDK deve incluir bibliotecas, documentação relevante, exemplos de código e implementação, explicação de processos, guias para uso de desenvolvedor, limitações em definições e todo tipo de oferecimento de facilitador para construir funções que alavanquem sua API.Para mais infos: Developer Experience

Melhores Práticas

Com o pensamento de melhorar a área de atuação do desenvolvedor, quais são as melhores práticas para a criação de uma SDK?

Simplicidade

Uma SDK só é valiosa se o usuário padrão conseguir utilizá-la. Bases de códigos complexas, implementações arcaicas e metodologias “labirínticas” são motivos para não se usar uma SDK. Garantir simplicidade sobre todos os estágios de criação é uma boa maneira de se construir uma base.Enquanto há uma gama de maneiras de atacar esse problema, existem passos acionáveis que desenvolvedores podem tomar proativamente para simplificar o resultado, como priorizar inicialmente classes e métodos que são os mais usados comumente. Isso permite que a SDK mostre as funções utilizadas pelo usuários sem ofuscar opções com um volume de métodos/funções que não serão realmente utilizados.Além disso, o código pode garantir simplicidade para a SDK, por exemplo, ao utilizar a menor quantidade de parâmetros possíveis para garantir a usabilidade da função. Como um corolário dessa última sentença, não devemos simplificar mais que o mínimo, misturando funções, visto que isso gera uma complexidade maior.Simplicidade é sobre forma e função – manter isso em mente trará uma SDK mais simplificada.

Usabilidade

Como mencionado anteriormente, o valor de uma SDK é a sua função. Dessa forma, garantir usabilidade é fundamental. Isso pode ser feito de diversas maneiras. Primeiro, prover um guia, talvez no modelo de um Getting Starter!, para ajudar a introduzir a SDK e todas as peculiaridades intrínsecas do código.Idealmente, um usuário deve ser capaz de começar a usar a SDK em 5–10 minutos de introdução, assumindo que esteja familiarizado com a linguagem e função do código que representa a SDK. Estruturar o seu tutorial de Boas Vindas em volta dessa meta.Também é muito importante garantir que a maior largura de usuários consiga utilizar seu serviço. Dessa maneira, oferecer SDKs que integram com o codebase da API em uma gama de linguagens pode ajudar a expandir a profundidade das opções disponíveis para mais usuários.É notável perceber que ao expandir os oferecimentos de linguagens, entretanto, você deve garantir o suporte correto dessas integrações, como utilizar tipos de arquivos corretos, sistemas de encoding e código em geral.Relacionado: Blocos de Construção: Suporte, Atualizações e Pesquisa

Mapeamento de Endpoints

SDKs são como roadmaps — eles provêm um guia para navegação, então, quando construir SDKs, garanta a corretude do seu mapeamento.Endpoints devem mapear na sua SDK da mesma maneira que mapeam na API. Fazer essas conexões o mais claras possíveis, o por que dessas conexões e o que são as respostas esperadas cria facilidade para utilizar a SDK.Garanta também o update contínuo das suas SDKs. Código depreciado, nomes de classes, funções não residem na SDK se não residem mais na API — deixar esses é criar a vulnerabilidade necessária para criar interseções me um mapa que não existe, nulificando muito do valor navigacional para o usuário padrão.Adjunto a isso, garanta que as funções estejam mapeadas e nomeadas apropriadamente. Enquanto isso é uma boa prática para a API, no SDK é ainda mais importante. usernameSubmit significa muito mais que unameSub, independente da praticidade de escrita de variáveis. Usar nomeações consistentes não vai só fazer a utilização da SDK mais simples, vai resultar em uma comunicação mais clara das funções, trabalhando como documentação ad hoc.Finalmente, garanta que toda nova funcionalidade é imediatamente adicionada e definida junto ao SDK, agregada também a documentação. Classes ocultas devem existir apenas por razões de segurança, não porque alguém esqueceu de adicionar.Leia também: Métodos para comunicar mudança na sua API

Documentação

É comum pensar que a SDK é uma forma de documentação para a API em adição a uma ferramenta de desenvolvimento. Entretanto, focar apenas no SDK como forma de documentação resulta em uma situação na qual os usuários mais técnico, que provavelmente entendem as funções naturalmente, são os únicos com alguma documentação valiosa.Dessa maneira, é importante prover uma documentação ampla não só da sua API, mas também da SDK. Além de tentativa e erro, esse vai ser o sistema principal que desenvolvedores (experientes ou não), utilizam como ponto de integração. Documentação pobre da SDK e suas funções pode quebrar o fluxo de trabalho. Vale a pena garantir que você está escrevendo claramente para usuário técnicos e regulares para prover entendimento universal.Para mais sobre documentação, leia: Dicas para melhorar a documentação

Publicações

É importante garantir que sua API possa ser acessada de maneira correta, e que esse acesso seja públicamente navegável. Se sua base de usuários é primariamente preocupada com segurança, desenvolvimento e open-source, ter sua SDK publicada utilizando GitHub e seus repositórios associados como um projeto open-source pode garantir resultados excelentes.Por outro lado, se sua API é fecha ou requer privacidade de código, então faz sentido utilizar uma metodologia de SDK e documentação proprietários, com o entendimento que tal “approach” carrega expectativas e ressalvas.Desenvolvedores devem considerar publicar a SDk em um ambiente offline, permitindo utilização da documentação e da SDK sem conexão com a internet. Isso pode ser feito de diversas maneiras, de um simples PDF à uma aplicação desktop construída com esse propósito. Independente do método, a escolha deve estar alinhada com as políticas de uso da sua plataforma.

Conclusão

Em essência, uma SDK é um canal direto com a mente do criador da API. Os vários métodos, sistemas e integrações do criador da API não estão somente presentes (como estão na própria API) na SDK, eles estão bem explicados e demonstrados — dessa maneira, uma SDK oferece um grupo de ferramentas para criação, mas também fornece um canal de comunicação que é direto, customizável e gerido pelo provedor da API para explicar e descrever de seu jeito específico.Uma SDK deve ser considerada como um sistema de extrema importância. Construir uma SDK pobre garante que qualquer comunicação ente desenvolvedor e usuário vai ser igualmente pobre, cheia com adivinhações e extrapolações que podem ou não ser verdade. Para isso, seguir algumas práticas aqui ditas vão garantir que seu SDK, assim como os sistemas que o utilizam vão ser otimizados