{{announcement.body}}
{{announcement.title}}

SDKs and World Class Developer Experience

DZone 's Guide to

SDKs and World Class Developer Experience

Take a look at SDKs and world-class developer experience as well as what languages to support and creating the GitHub repository.

· Integration Zone ·
Free Resource

This article is featured in the new DZone Guide to API Management: Comparative Views of Real World Design. Get your free copy for more insightful articles, industry statistics, and more!

Developing an SDK for your API can significantly increase the developer experience by providing native support for a developer's preferred programming environment. This article will describe some best practices, strategies, and processes to help your API provide a world-class developer experience.

Choosing What Languages to Support

When launching support for multiple programming languages, build the SDKs out one language at a time. Ideally, interview a sample of your customers and find out what languages and platforms they prefer. If that's not feasible, use one of the surveys released by GitHub or StackOverflow and choose one of the top three to start. Continue your research on GitHub, searching for any open source code that already utilizes your API.

You can also try creating some basic documentation with pageview tracking that demonstrates how to interact with your API using basic calls in several popular languages. Put each programming language example on its own page and observe the page views to help inform your priority.

As you release the SDKs, include a user agent in the header to record usage data, which can then be used to help calculate your RICE score (a method of prioritization), as explained in further detail in the Prioritization section.

Supporting Programming Languages You Don't Know

In this case, develop a one to two-week learning sprint before diving into the development of the SDK. Start by consuming high-level content, such as the philosophy behind the language and the common use cases.

Discover the key people behind each programming language's community and consume their content. Reach out to people in your network as well.

Build an HTTP client that consumes your API using the native methods of that programming language to cement your knowledge. Finally, take some time to explore a few quality SDKs from top-tier API providers.

Creating the GitHub Repository

At a minimum, your SDK should provide documentation and tested code hosted on a platform such as GitHub. Often, your documentation will live in at least two locations: GitHub and your official website. Keeping these documents in sync is a challenge, therefore, utilize the OpenAPI specification as the source of truth for both your documentation and code.

While you can write the OpenAPI specification by hand, do not take that approach as it's generally tedious and prone to error. Services such as StopLight.io and Apiary.io allow you to define your API with a pleasant UI that's well-suited for collaboration and then export the results as OpenAPI-compliant JSON.

Many open source SDKs contain, at a minimum, the following elements: the code, LICENSE.txt, README.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, USE_CASES.md, CHANGELOG.md, TROUBLESHOOTING.md, and a set of labels applied to each issue or pull request. For an example repo that embodies these elements, please see this repository.

But first, take a moment to set up the repository metadata. Near the top, you can add a description, website, and topic labels. As you build out your SDK, keep a journal to document your process. As part of this journal, create checklists for anything you need to do more than once. Make it a habit to utilize the checklist each time so that you can continue refinement. When you feel like the checklist is working smoothly, look toward automation and process documentation.

The Code

DKs consist of two layers: the interface to the API and the helper code that helps execute specific use cases. The former can be automated, and the latter is key to the developer experience.

The helper code should be lovingly crafted, preferably in collaboration with your users. Start with a usage guide published in your GitHub repository that demonstrates how the SDK would work when completed. Then, invite your open source community into a conversation around that document, encouraging comments and pull requests. I found that specifically tagging people in the comments works best to initiate the conversation.

For testing, Stoplight.io provides a free service, Prism, that turns any OpenAPI specification JSON into a live mock server to run your integration tests against. My preferred workflow is to spin up an instance of Prism in a Docker container for local testing and in Travis CI. Utilizing this strategy allows you to skip learning and implementing the specific mocking features for each programming language you support.

LICENSE.txt

Determine the license that is most appropriate for your situation and put in a LICENSE.txt file in the root directory. Utilize ChooseALicense.com to help choose an appropriate license for your project. For a complete reference of open source licenses, refer to OpenSource.org/licenses.

README.md

A README is perhaps the most important document in your repository as it's usually the first impression someone has of your project. At a minimum, your README should contain the prerequisites, installation instructions, and a quick start example with the goal of getting your user to their first API call as quickly as possible.

Additionally, I recommend that you include the following elements in your README:

  • Summary
  • Logo/branding
  • Build status badge
  • Table of contents
  • Announcements
  • Quickstart example
  • Roadmap
  • Links to
    • API documentation
    • Use case documentation
    • Contributing guide
    • Troubleshooting guide
  • About section

CONTRIBUTING.md

This document should be designed such that anyone can easily contribute to your repository, from fixing a typo to implementing a brand-new feature. Cover the following topics in your contributing guide:

  • CLA/CCLA/DCO requirements
  • Roadmaps & milestones
  • Submitting a feature request
  • Submitting a bug report
  • Suggesting improvements to the codebase
  • Understanding the codebase (a high-level overview ofthe code)
  • How to install a developer environment and run the tests
  • Style guidelines and naming conventions
  • How to create a pull request
  • How to conduct a code review

CODE_OF_CONDUCT.md

The code of conduct should set the tone for your community while describing a reporting mechanism for violations with a clear description of the consequences. Check out GitHub's built-in code of conduct functionality for inspiration.

USE_CASES.md

Your "getting started" documentation may be THE most important key to a world-class developer experience. Here, you need to define the most important jobs to be done for your customers. The goal is to get them from reading this document to making their first API call as quickly and easily as possible.

CHANGELOG.md

In addition to leveraging the release functionality built into GitHub, create a CHANGELOG.md file that minimally includes the semver version, release date, and the type of changes (e.g. fixes, features,etc.). I like to link each entry to the original pull request, issue, and the contributor's GitHub profile along with a note of thanks.

TROUBLESHOOTING.md

First, try to think of common issues that your users may experienceand document them here. As issues are reported, documentany workarounds or gotchas here. Then, use this document tohelp you drive an improved developer experience over time byexamining how you can remove each issue from this documentthrough improving the SDK's functionality.

Labels

GitHub labels can be used to communicate the status of an issue or pull request and to trigger automations. Here are some labels to use as a starting point:

  • Difficulty
    • difficulty: easy
    • difficulty: medium
    • difficulty: hard
    • difficulty: very hard
    • difficulty: unknown or n/a
  • Type– type: bug
    • type: enhancement
    • type: docs update
    • type: question or discussion
  • Status
    • status: duplicate
    • status: help wanted
    • status: invalid
    • status: wont fix
    • status: cla or dco not signed
    • status: code review request
    • status: ready for merge
    • status: ready for deploy
    • status: work in progress
    • status: waiting for feedback
  • Misc
    • hacktoberfest
    • up-for-grabs
    • up for grabs
    • help wanted
    • spam
    • good first issue

Then, you can apply the following process upon in taking each issue or pull request:

  1. Assign a Difficulty
  2. Assign a Type
  3. Assign a Status
  4. Optionally assign a Misc. label

Support, Collaboration, and Management

One key to scaling the number of people your project can support across many programming languages is to collaborate with your open source community. Serve them well and they will return the favor.

Encouraging Collaboration

Why would someone donate their time to your SDK for free? Whatever the reason, you should be rolling out the red carpet.

Be respectful of their time and personally respond to every question and comment. Sure, that part is tough to scale, but if you expect your community to support you, provide them with as many reasons as you can. Simple, timely communication is the baseline.

As you develop relationships with your community, take special note of your top contributors and actively seek their advice. If possible, speak to them on the phone, through video chat, or ideally in person.

Chances are your company relies on open source for many projects, so it's natural to encourage giving back. Utilize internal communication platforms to seek out open source advocates and form relationships. Leverage internal newsletters to create specific calls to action. For example, perhaps one of your SDKs could use some help with code reviews, so send out an email with direct links to where help is needed along with detailed instructions on the process.

Roadmaps

If you take the time to expose your roadmap, you can learn whether it resonates with your community while also offering an opportunity for potential contributors. You can either use the built-in milestone and/or project feature in GitHub, create a simple ROADMAP.md file, or create groups of issues tagged with roadmap labels.

Code Reviews

Performing code reviews can be time-consuming, especially if the code is written in a programming language that is not part of your expertise. By defining the process for performing a code review and codifying it in your .github templates and CONTRIBUTING.md files, you can make it easier to solicit help from your community.

Issues and Pull Requests

Issues can be used to ask questions, report bugs, and request features. Encourage all three of these scenarios as well as commenting on issues. Document the process for each of these scenarios in your .github templates and in your CONTRIBUTING.md files.

A pull request can be in response to an issue or spontaneously submitted. These are both fantastic, but additional care must be taken on the latter since it's unwise to simply accept a pull request that does not have a high RICE score (see the Prioritization section below for further details). Have a strategy for saying "no" without severing the relationship.

When a new issue or pull request comes in, utilize your labeling process and apply automation to appropriately prioritize. Respond to incoming issues and pull requests at least once per day manually, even if it's just to say that you received the issue and will follow-up at a later date. You may also want to employ an automated message that guides the submitter to next steps and expectations.

Pull requests are the ultimate expression of developer love and should be treated as such. Whenever possible, prioritize these.

Prioritization

Utilize the RICE prioritization method: Reach, Impact, Confidence, and Effort. The idea is to assign a numerical score to each incoming issue and pull request, computed using this formula:(R*I*C)/E. This score can be used to determine what you should work on next.

  • Reach can be computed by estimating how many of your users this issue or pull request would affect.
  • Impact is subjective, keep it simple with categories like large, medium, and small.
  • Confidence is your idea on how much confidence you have in the reach impact and effort estimations.
  • Effort is how difficult you think it will be to complete.

The Backlog

I like to keep two backlogs for managing SDKs: one for projects and the other for issues and pull requests, assigning portions of the day/week to each of the two backlogs. To start, begin with a spreadsheet and, once the system is working efficiently, converting the system to a database driven application.

Release Management

To make the developer experience seamless, deploy your SDK to the relevant package managers. Depending on the frequency of contributions, either release on-demand or batch releases at some predetermined cadence. Define both cases because, at a minimum, you will need to utilize on-demand releases for bug fixes.

Below is an example release checklist. (Note: you need to fill in the details for each bullet point with enough detail that you would be able to outsource or automate the entire process):

  1. Ensure all tests pass
  2. Ensure code review is complete
  3. Update CHANGELOG.md
  4. Update README.md
  5. Update CONTRIBUTING.md
  6. Update USE_CASES.md
  7. Upload to package manager
  8. Update releases section in GitHub
  9. Perform post-release smoke test
  10. Announce externally

Adopt a versioning standard and consistently apply it to every release. Be very careful with this as it's a trust indicator, especially when it comes to breaking changes. Follow the semver standard and clearly define what patch, minor, and major version bumps mean.

Thanks!

To continue the conversation, please reach out on Twitter @thinkingserious! Happy Hacking!

This article is featured in the new DZone Guide to API Management: Comparative Views of Real World Design. Get your free copy for more insightful articles, industry statistics, and more!

Topics:
integration ,apis ,sdks ,developer experience ,github repository ,code reviews ,release management

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}