An OpenAPI spec is about more than auto-generated reference docs. Here, APIMatic’s Ameer Hassan shows how OpenAPI specs can impact the full developer experience, in his talk from DevRelCon London 2018.

Transcript

Hi, I’m Ameer. I’m a non-developer who really loves to help developers, and today, I’m actually helping out a fellow developer, Haider, by filling in his spot. You can find me at [email protected].

Developer geography

So, yeah. Today, I’m here to talk about developer experience. So, of course, when you talk about developer experience, you’re talking about your target audience, which is essentially the developers. And if you are able to speak their language, or provide components that they need to easily consume your API, you’re providing, essentially, a good developer experience, and ultimately, consequently, getting a good consumption of your API as well.

So, let us start by asking a question. How many developers do you think are there in the world? Three? –

Audience member: At least twice that, six.

Ameer: Six? Yeah, I like the number. Actually, according to Stack Overflow data survey, there are 50 million developers across the globe. Out of which, 21 million are professional developers. And you can see the distribution across the globe, again, taken from the same data from Stack Overflow.

The link is down at the bottom. By the way, we’re, right now, sitting at probably one of the highest concentrations in the world of developers. So, good place to be, I guess. So, when we were looking at this data, it got us thinking that, hey, developer experience, we know, is a fairly recent phenomenon in a sense that we’ve recently started talking about it, and sort of it got mainstream very recently.

Developer history

But developers are nobody new. They have been around for more than half a century now, right? So, that actually got us thinking about the basic, in a sense, “Hey, how was developer experience handled back then?” So, let’s say in the 50s and 60s. So, let me quickly take you through an example.

So, I don’t know if there are many old-school developers over here as well. So, that’s of course a machine code snippet. Would anybody be able to guess what exactly is that? Well, let’s take a wild guess.

Audience member: Hello world.

Ameer: Well, that, I don’t know think, no, but yeah, here we go. All right, so, yeah. It’s a simple swap function, so just swapping the variables over there. And you have a high-level language code, and consequently, there is an assembly code, and then there’s machine code. So, that’s how it ultimately evolved back in the day.

Moving into high-level language

Right now, developers code in high-level language. Right? But it still gets, you know, compiled and processed into assembly and into machine language. Why? Because our machines still speak in binary, right? But the thing is that everything else is done at the back while we look at the high level-language code.

So, that got us thinking, why is that? Right? Why don’t developers do machine language anymore, right? Because it’s, of course, non-productive and unnecessary, because we’ve got systems in place who can take care of that, the non-productive or non-creative bit of that.

So, that was our aha! moment for developer experience. So, essentially, developer experience, to us, has always been about letting the developers focus on what’s creative and abstracting out whatever is non-productive or redundant out of their lives. That’s essentially making their life easy and getting a good experience.

APIs and developer experience

Fast forward to today’s API world, so, let’s try to apply this analogy moving forward. So, there’s always a list of developer experience for API world. There’s a list by somebody we really adore at APImatic, Kin Lane.

Again, he lists down some components that are really essential for providing a good developer experience. Today, I’m only going to be talking about just two of them, SDKs and code samples. Why? Because it gets important when you get to these components. That’s when the complexities start to kick in. By the way, feel free to tweet about it.

Right, so, it’s these components where the complexities start to kick in, and you have to deal with challenges, different challenges. For example, this again is the distribution of same 50 million developers from Stack Overflow distributed into different communities based on languages.

The language challenge

Right? So, it becomes important, and it becomes basically dependent upon the API providers which community would you drop if you don’t have expertise in that language, or if you don’t speak the language of that community. And again, it, I think, ties back to what the philosophy that Don was mentioning when he was talking about, you know, flying example.

So, you might end up missing out a community. For example, let’s say that you decide that you’re not going to have your documentation for, you know, Python. So, take yellow guys out of this picture, because you’ve just simply excluded that community. So, moving on, in order to help, you know, API developers, let’s have, again, a look back at a very basic concept of an API call.

So, an API call, of course, essentially, comprises of input, and of course, you get a response in the form of an output. And what sort of input does that developer get? So, configuration, arguments, authentication credentials, and after getting these inputs, a developer goes through a process, right, a series of steps.

So, checking and validation, encoding, serialization, building HTTP request, making a call, deserialization, decoding and handling errors. Right? So, developers are great, they’re amazing problem-solvers, so your developer would definitely go through these steps.

But again, keeping in mind the same analogy of machine code where it says high-level code, which of these steps are redundant? So, it turns out, all of these steps can be encapsulated and sort of packed in a box in the form of an SDK, and can be provided to your developer.

Ways to help your developer

And at APImatic, we’ve been dealing with SDKs, auto-generated SDKs, for about four years now. And we think if you take care of an HTTP call and serialization and deserialization, your basic SDK is done. But why stop there in helping your developers?

So, how about you take care of the other redundant things like caching, retries, validation, authentication, linking, and so on? So, for example, your API, you know, your API takes two-legged flow.

Right? So, of course, developer can go figure out in generating tokens and, you know, keeping it refreshed every 30 minutes. But why not do that for him? Wouldn’t that be a great experience? So, this is what we believe that, you know, automating all these redundancies can really alleviate your developer’s experience.

And at APIMatic, what we do is we do all of these, and rate all of these, from one single source of code, your API spec. Moving on to the second item, code samples, your quickest way to force Hello World. So, they become really important as well.

So, initially, when we were dealing with SDKs at APIMatic, we relied on our customers to bring their own code samples and generate SDKs. And there are of course many tools out there that do some sort of, you know, generation of code samples for use, some sort of basic code samples.

Creating dynamic code samples

So, let’s look at an example. Here’s one example of a code sample that’s available out there. So, when our teams looked into that sort of solutions available, there were two issues that we found out. A, those code samples were mostly static, which means that a static code sample is available.

The developer would have to add on the unique or the creative bits to it to make it work, A. And B, they were incomplete, so they were more of a code snippets that were not in, say, compilable forms. And of course, developers would have to figure out ways to add on code to make it complete. So, recently, what we have been doing is the way we found a solution to this problem was what we call through dynamic code samples, or reactive code samples.

So, what we do is we’d take that static bit of code sample, and we allow the developers to basically inject those unique items, those variable items in those code samples to make them more complete.

And we do that via an API console. I’m sure you guys would have seen many consoles that are out there, so I’ll just quickly go to a few examples on what do I mean by that. So, here you see on the right, there is a console. There, you could see the code is being populated. And on the left, you can actually see the parameters where the data is being put in.

So, an email address, for example, is being put in, and you can see that it’s updated. I don’t know if it’s got a pointer, yeah. So, it’s updated right in the code. And Erin, you were just giving an example of that API client ID in secret. So, we do that, too. We highlight it so that it becomes easier for a developer to interact with that static code, and it really makes their life easy.

So, here, if let’s say I click “Add new”, so there is create share pay load. I entered my email address, Adil’s email address here, and if I click in, so you see that some further fields open up.

There are text boxes where I can enter the data, and you see on the right, the code is also populated. So, but then, there are some fields that require multiple choice. Right? And you usually, if you have good documentation, you would have sorted that out in your documentation.

The creative, customised code sample

So, of course, your developer could go back, look at what are those options, and you know, fit that in the code. But what if you provide them as a multiple choice right from your documentation over here, you see if I click, let’s say “Enterprise”, over here, so a variable is created, company type.enterprise, so that all is happening in real time.

So, again, this is a code snippet, the incomplete problem that initially mentioned. It’s again a code snippet, but it’s done, so you can copy it and paste it in your application, and get away with that. But what if you’re writing your first Hello World, and you’re writing your code from scratch?

So, if I click show complete file, so a complete set of codes appears where you don’t have to work around too much and, you know, get away with writing as minimum code as possible.

So, basically, again, the same idea of developer experience, the same philosophy of developer experience that tries to keep the redundant bit automated, but then, the creative bit should be incorporated in there. So, that’s what we do with our code sample as well. You see, the static code is there, but then, there are some item that are unique, so authentication, client ID, client secret is there, payload, body, this hello from APIMatic you see.

So, these are the things that, you know, our developers can come in and just interact and generate their own customized unique code samples. And again, all that is done through a single source of truth, your API specifications. One thing you might have noticed is that here, we talk about client ID and client secret, the only two things. Right? So, authentication bit is done at the back.

What should developers be doing?

So, to conclude, what developers should be doing, so of course, there are two sides to an API. On the API provider’s sides, developers should be busy in, you know, exploiting the business proposition, and the value proposition of your business, and converting that into beautiful APIs.

And on the consumer’s side, developers should be busy in using those APIs in creating beautiful apps. But what they end up doing is, on the provider’s sides, they are creating, testing, updating, documentation, portals every time the API changes or updated, code samples by hand, SDKs by hand, sometimes not by hand as well. On the other side, you know, the consuming side of the developers, they’re busy in HTTP logic, authentication, retries, and caching. Again, the redundant bit.

So, again, applying the same principles, we think that using again the same source of truth, single source of truth, your API specification, we can take that redundant bit and automate it for developers so that they can focus on the creative bit of development.

I’d like to conclude by a quote that’s really popular at APIMatic, we really love it, by Nelson Mandela. So, “If you speak to a developer in a language that he understands, that goes to his head.”

Sorry, not developer, a man, right? “But if you speak to him in his native language, that goes to his heart.” And developers are no different, right? So, if you speak the language of your developers, you would make their life easy in consuming your API and would get a lot of love in return.