Redefining SDKs as software diversity kits


Sid Maestre speaking at DevRelCon San Francisco 2019

Sid Maestre

Head of Developer Evangelism at Xero, Sid Maestre talks through the biases and challenges in building SDKs to support a diversity of programming languages on your platform in this session from DevRelCon San Francisco 2019.


Today, I’m going to be talking about the challenges of supporting multiple programming languages, the diversity of programmers that are out there today, and also, what we’re doing at Xero to try to address that.

So, my hypothesis is that companies benefit by increasing the diversity of programming languages that they support. And one of the challenges that I’m going to talk about today, interestingly enough, is tribalism.

When I started thinking about this talk, I was thinking about all the different technologies that are out there, Internet of Things, VR, AR, blockchain, and all the programming languages as well. And I thought about, you know, on meetups, online, why do we, you know, form all these groups? You know, why are humans doing this?

And it got me thinking about thousands of years ago, you know, how we formed these tribes. Basically, they were our families and it was this kinship we had with others, and we needed that to survive. I mean, it was a pretty harsh world we were living in, but in modern society, who we bond with has changed a lot.

Need to connect

But we still have that desire of belonging, that need to connect, but now we actually get to choose our families, whether they’re fellow programmers, the people we work with, or the activities that we do outside of our work.

And this story kind of comes from a personal place for me. This is my desk back in the mid-2000s. I’m working at the university as the lone developer there and I felt really isolated, no one to share the latest JavaScript library I’d found, no one to geek out with, no one like me. And I wanted to connect with other people and share, and to grow. And so, I went to my first big tech conference.

Anybody recognize this? Adobe, Adobe MAX. And I went to this conference and I was just blown away. And I thought to myself while I was there, like, “Wow, I’ve found my people.” Ran home, joined the local user group, started my own meetup, went to more conferences, started speaking, ended up in developer relations somehow. That’s where the passion, I think, started. If you don’t like my talk today, you can blame Adobe.

Love of the same

But while doing this talk, I started digging more to this whole idea about tribes and groups, and why we form them. And in the 1950s, there was a sociologist that coined the term “homophily,” which means love of the same. And I think that feeling I had at the conference, that’s what he was talking about and there’s so many good things spring from these tribes that we form.

In fact, I think it’s this love of the same that binds us together even when there’s conflict. There’s no conflict there, but it’s our shared interest in things like programming, like maybe the guy next to you or person next to you in the cubicle is a little bit annoying at times. But you’re able to put those differences aside because you have this shared interest.

And you’re often loyal to your tribe. You don’t abandon it easily and, you know, thousands of years ago that was pretty important because your life depended on the person traveling with you.

Us vs them

But, often, the way that we define our group and tells the world who is us, we often tell the world who’s not us. And while that’s a really effective way to define a group, it can have some downsides.

Because I think, you know, our brains are really hardwired to look for these patterns subconsciously. When we meet people, we look for signs, you know, are they with us, you know? Or are they one of them?

And these skills, when we had them thousands of years ago, we developed them, you know, our lives often depended on it when we met a stranger. But I really think there are some, you know, those bad side effects.

And what I think happens in our programming language communities is that we want to, you know, we get these benefits, right? And we support each other and there’s all these good things that come out of it. We have a blog posts, tutorials, we share code on GitHub. There’s tons of benefits.

So, you know, don’t get me wrong. Programming languages, tribes, groups, all very good. But, when we adopt this us-versus-them stance, it can devolve sometimes into ridiculing entire developer communities and we can dismiss the work of thousands of passionate developers in order to sort of define who we are versus them.

Hidden bias

And I think that’s one of the challenges that we face. I think we end up with this hidden bias with this us versus them. We assign characteristics.

Now, I’m going to have a personal confession now. I may have had a poor interaction with a Ruby developer in the past and I actually have to be conscious that when I interact with a Ruby developer, I’m sure there might be one in the audience, I have to make sure that I check that bias I might have because of that poor experience in the past.

And it got me thinking about all the different programming languages that are out there. This is just a random selection. I charted them based on age, how long they’ve been around. I’m sorry if I don’t have your favorite language up here.

But it got me thinking, you know, as a programming language ages, probably the developer community ages along with it. I mean, if you’ve invested a decade or more becoming really deeply skilled in a language, you don’t necessarily want to give that up for the hot new thing, right? Though if you’re into challenges, you might be jumping from language to language and that’s okay.

But I also think maybe we might end up with an age bias if we exclude languages that are much older. We also might find that we’re not interested in Rust or some new language because it’s just too new, it’s too experimental. So I think a new programming language might get, might face some of those biases as well.

Programming language geographies

And this got me thinking about geographies. I started thinking, “Well, what is the popularity of languages in different parts of the globe?”

So, I fired up Google Trends, totally unscientific, I’m sure, but I thought it was interesting that number five is New Zealand, which my company Xero is based out of New Zealand. And I’m always being told, Microsoft and C#, and .NET is all, is very popular in that country and this kind of validates that thought. And then I thought, “Well, let’s look at PHP. It’s popular in the Ukraine and different parts of Europe.”

And it got me thinking, as U.S. companies, we might have some geographic bias because we’re always talking to people in the U.S. about what languages are hot, and popular, and which one should we support. And we can limit our diversity by that.

Inclusive behavior

So, this was a real roundabout, detoured way to get to where we are, but I want to talk about those things as challenges and then think about how we as developer relations can maybe be a little bit more inclusive. I want to sort of think about ourselves, our companies, and our communities that we work in.

And I thought, we should probably start by looking at ourselves, maybe examining any preconceived notions that we have. When I say Python, or PHP, Clojure, .NET, does anything pop into your mind as far as the age of that developer, the nationality, the gender, perhaps an individual you had a positive or negative interaction with?

And as developer relations folks, we all know, empathy is really one of the most important characteristics of the work that we do. And, like I said, you know, about the Ruby developers, you know, I’ve been in a meeting and I’ve made a joke about another programming language or a community, and I’ve leaned on a stereotype for a laugh. I think I can do better and it’s definitely, this talk has made me think more about any of those biases I might have.

And as developer relations people working in a company with other engineers, you know, we have the opportunity to influence people. You know, think about Stack Overflow or your developer forums, and a case comes in or a ticket comes in for a language that you don’t support or you don’t think is very hot.

Do people make jokes about it? Do people ignore it? Maybe you could model the behavior of asking around, “Has anyone seen this question asked before?” “Are there any libraries out on GitHub that could help this developer?” Or maybe it was answered on another forum you can link to.

So, by being more proactive, we could actually help the people around us be more inclusive.

And then, of course, because we’ve gotten to speak to the developer community, at a minimum, we should avoid those disparaging comments about other languages that maybe aren’t the ones that we favor and try to promote a more open and inclusive view.

Software diversity kits

And that brings me to the topic around diversity through SDKs. And before I get to SDKs, I’m just going to talk about Xero and sort of where we are because I’m sure some people in the room may have walked in thinking, “There’s no way I’m building 20 SDKs and supporting, you know, 20 languages,” and I would never ask anyone to do that.

We don’t do that at Xero, but I’m going to talk about what we do do to try to be more inclusive. And this has evolved over the last five years with my goal being to support a more diverse developer population.

So, at Xero, our SDKs are handcrafted like artisanal beer, each one lovingly built. And can anyone guess which one probably has the best support?

You’re right, .NET. Why is that? Because we have a team of .NET engineers in New Zealand who are more than happy to lend a hand because nobody’s job is to build these SDKs.

So, people on the team raise their hand, I had an evangelist on my team raise his hand because he was curious about Golang. He built an SDK, we put it up on GitHub. He’s not on my team anymore.

Problems building by hand

And honestly, there’s a problem with building these by hand. They can get neglected, people can get burnt out because it’s not their full-time job, and developers might suffer from that.

You could go to the GitHubs and you could search for your company, and find some public, you know, some open source projects built by people in the community. We’ve done that and we’ve anointed ones to be the official, you know, Ruby library. By the way, Wayne is a wonderful guy.

But you end up with mixed results with that because, from my experience, these projects start with loads of enthusiasm. But over time, the developers have other work to do and they may not be able to review pull requests. They might be strongly opinionated and hard to work with.

But at the end of the day, it’s not really their full-time job to build and maintain SDKs for your company. In fact, those relationships can get a little bit strained. We were deprecating TLS 1.0 and so we thought, “Oh, we better reach out to some of these community libraries and give them a heads-up.” And our message was not always received warmly.

So, I guess, you know, the way I look at this and I don’t want to end this on a sour note, these open source projects, these SDKs that your community might build, they’re doing a great service. But this is really the icing on the cake, right? I mean, this is a sign of developer engagement and that’s a great thing. But there are risks in relying on it to be your official SDK.

Non-language specific supports

So, what are we doing at Xero? Well, we are rolling out support for OAuth 2 this year. I know. Don’t judge. We’re still on 1.0a. But we have 700-plus app partners who are going to need to migrate their integrations, thousands of developers, and we’re building some SDKs, of course. But before we get there, what we’re also going to do is offer this non-language-specific way, like the vanilla implementation.

So, we’re going to use Postman. I’m sure there’s other tools out there that you can use, but for any programming language, they can look at that Postman example, and they can understand what’s unique about how we’re doing the OAuth 2 and they can implement it.

We’re also building just vanilla OAuth 2, no SDK, just, like, multiple languages. Like, off the shelf, I just pull down this NPM package, this is how you can connect to our API.

So nothing fancy, but if you give multiple examples, you know, I might be a Python developer and I can look at the Node one and I can learn enough from that to roll my own solution, which I’m sure a lot of developers want to do.

But we actually do want to provide full-blown SDKs and we’ve discovered the limitations of building them in the house or having the community on them. So what we’re doing is we’re creating blueprints.

We are creating an OpenAPI spec, there’s other ones out there, but we’re starting with that and we’re using code generators. I got to speed up a little bit.

Creating your spec

But what we’ve done is we took an existing spec and I brought it into SwaggerHub. You can use other tools, but we found this really helpful. We learned a lot about how to validate our syntax and make them better.

And I also found that you can connect it up to GitHub, and every time you hit Save, it actually commits to your repo an update to a branch that you can later merge in. So, really nice way to build your specs.

If you get your specs from someone else, you may want to be careful about completeness and accuracy because they may not have built it for your use case which is for generating client libraries. I call it the garbage in, garbage out rule.

So, don’t just take a spec that someone gives you and give it to developers because when they use a code generator, it may not actually generate the right kind of code. There might be some problems with it.

Pick a client SDK to build

So, how did I actually test for completeness? I actually built an SDK and I chose to use Java. Now, you can use any language, but I actually found that was a really nice way to do it.

We had done everything in XML and so, we were generating the new library using JSON. So the old code and the new generated code ran side by side, and we could release it to the developer community, and get some brave souls to give us some feedback.

This was the result of that feedback. These are the commits to our OpenAPI spec. The really cool thing was that 95% of the feedback was fixed in the spec. I actually didn’t have to write any Java code and I was able to do 23 releases in 2019 so far.

Audience member: That’s awesome.

Sid: So, it was really cool.

OpenAPI code generator, that’s what we chose. Its a fork of Swagger Codegen. I’m not saying one is better the other, but they give you all the language templates, the bash scripts, and you can actually start modifying and playing with those.

This is an example of the command-line parameters which are, like, what’s my template, where’s my OpenAPI spec, what language am I using, and where do I want it to output. I watched a one-hour webinar and was able to start playing around with OpenAPI specs, and downloading code generator. So, it was very cool.

What did I learn? I learned that it doesn’t come with your authentication as part of the generated code. So, you have to go find your own OAuth 2 library, which wasn’t too hard.

I thought the strongly typed language, Java helped me find a lot of strings that should have been dates or strings that should have been numbers.

I also found that a developer was unhappy with our Java docs because the descriptions were very generic and poor. So he gave me that feedback and I updated the spec, regenerated it, and he was happy.

Your API might have a few quirks. So, watch out for those and you want to let developers know about those.

I’ll skip over this real quick, but basically, if you haven’t played around with Mustache templates and you go down this path, you’ll learn a lot about Mustache.

This debug parameter was super helpful with OpenAPI generators because it actually spits out all the parameters you can use in your template and I was able to figure out how to fake my if else statements.

And lastly, you can actually mock your API responses with SwaggerHub. So I could actually return a static response and I built full unit test cases in Java, and that actually helped me, again, get more complete coverage of my spec. So, it was all in service of creating a really accurate spec.

Empathy for a wider range of developers

So, in summary, I think that we can do better. I think we can demonstrate this empathy for a wider range of developers.

I mentioned the biases that we might have, but also by creating these vanilla examples of how to interact with your APIs or your technology, and also, providing these blueprints because maybe you won’t generate the library for your, you know, your own company might not generate that library, but with that spec, developers can generate their own libraries and they support 20, 30 different flavors out there.

So, I’m really advocating for that at Xero and I think that it’s going to send a positive message to developers that we like them too. And that’s it.

Leave a comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.