Why Your New API Product Will Fail
CC Attribution - ShareAlike 3.0 Unported:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal and non-commercial purpose as long as the work is attributed to the author in the manner specified by the author or licensor and the work or content is shared also in adapted form only under the conditions of this
Feinberg, Scott
Congrats! You've built the one API to control them all, and it's amazing. It's fast, well-architected, and Level 3 Hypermedia. However everyone is still using your competitors sub-par product... Why? We developers are lazy and you're making it hard for us to use. We're diving into your SDKs tests to solve basic tasks, your SDK + API errors annoy and don't help us fix our mistakes, and the lack of logical defaults leaves us playing parameter roulette. Let's explore how to build API-enabled products that fellow developers will love using with great docs, tooling, support, and community.
 Thank you all for making the mistake of coming to my talk. Hi everyone, I'm Shannon. So my name is Scott. I work for what we call the Mojite. We're an API based payments company similar to Stripe. We do payments for people like constant and contact, media.com, and basically any credit run insane. So my title is, Why Your API Product Will Fail. As you might not know, if you want to get your talk on selected and you want people to show up to it, you should have something really click-by and ask for business. So the title probably should be something more along the lines of how to build an API tool in the business sector. My name is Scott. Some people confuse me for Taylor Swift. Sorry about the confusion coming in. I was also told that if I could just go down and occur, people wouldn't be mean to me. So today's agenda is what does good API toolings look like and how do I build it in a scalable way? How do I build it in a way where every time I launch a new version of my API, I'm not freaking out? Okay, so let's start with what is API toolings? But before we get there, how many people have ever used an API before? Most people, pretty much everyone. How many people have used an API that's sucked? How many ever used an API that did things that Dr. Jason said that it didn't do? Yeah, a lot of people. So what API tooling is meant to do when it's built well is to rent things like that from a company. So again, the consumers, that's us, need chance to use the MEPI in the way that it was designed to be used. Now remember that every time you use a MEPI, there was a developer, just like us, perhaps someone even in this room, who decided to write the dog on that, or wrote the actual MEPI. So consider that, not that you should be sympathetic, but that when you're doing it yourself, you don't have to do those same things. So API tooling is essentially two things. It's documentation that is reactable to a lot of API clients. Some people call them SDKs, some people call them wrappers, whatever you want to call them, they are the way that someone interacts with your API. Now if they want to use a curl client, whatever, but most people offer some sort of client-in-him library. So that documentation can be further broken down into tutorials, the actual reference docs, and the explanation and use cases of those API calls. So we'll start with the tutorials. How many people have ever, when they started using an API, tried to jump into the reference docs, you probably said, okay, how do we put this smallest thing that I actually do with this MEPI. Give me a how-to guide. So what does how-to-times do? Because it needs to tell you what you're actually doing. You've never used this on the API before, then you probably don't know. You're probably going to need some detailed steps. Steps that even perhaps the most junior person on your team would be able to follow. And also, I don't know about you, but I don't actually really like doing work. I really just like to copy and paste stuff. Ideally not off-stack and overflow. Ideally like from your docs themselves. I don't really know how to Google it, but make it easy for me. Make it easy for me to just sort of copy and paste, get going, because I don't really want to do work. Oh no. I don't know about you. So here's an example of what a tutorial on what's like. We should have some sort of explanation of what you're doing. We should have some sort of example, use case for how this might be used. And then before you actually just create a large own tutorial with lots of steps and copy and paste, you should actually probably tell the person from a high level, this is what we're actually doing. Because likelihood is if I probably don't know, I'm actually a page note. You might have a good title on it. You might not. Just tell me, okay, before I get started, I have to sort of go, wait, this isn't actually what I'm wanting to do. Because most tutorials, they're very text heavy. Don't make me read. So with each step, don't just include the code. Include some sort of like, this is what you're actually doing in this code. While it should be obvious, your code should be at least decent. It might not be that obvious to someone who's I'm assuming. So beyond tutorials, once you're actually using an app, likelihood is you're going to do something a little bit different. Something that may mean the tutorial writer didn't come up with. And that's what we're going to talk about reference. So these are the docs where you see all the calls and everything that a API does. So the simplest API call is, I'm going to send you an ID. You're going to send me an object back. It's a very simple get. So in this get, you're going to want to see, okay, so what's the parameters that I actually need to pass? Is it required? Do I need that? Why not just be one? It might be a few. What is the type of that? And then give me an example. Well, this one here is really basic. More complex stuff. That stuff is actually really neat. And then once that stuff is actually returned, you need to tell me what is it that you actually just sent? I don't know your app. I don't know the object structure. But you bring down for me what each of those parameters is and how I'm supposed to use it. And in addition to that, it's really nice when you give me like a JSON example to work with. If I don't have some sort of example data structure that I can call and paste into my code and actually start playing with, it might, well, like you're like, well, you can just make a call and then you can play with that. Not every call to your API can I immediately make. I might need some actual data in there first. So let me figure out how I'm supposed to play with it before I actually have to make a call. So in your reference docs, make sure that every resource is well undocumented. It's okay to visually duplicate things in docs because one of the worst things you can do is give me like a bunch of links to other pages and to actually understand what your, what an API call is doing. You're making me jump around. You're making me access three, four, five files to do one thing. And that's no fault. Also the requests and the response parties, make sure that I can copy and paste those. Make sure that I can actually see what those are. And hide those from. Don't make me make calls just to see what your API does. And for each parameter in those, make sure that those are well documented. Otherwise, you're going to have people emailing you or a support team asking, okay, what does this parameter do? It's not consistent. What's the problem? So explain what each of those are and how these use them. Now to actually build these sorts of docs, you need to first figure out, you first need to know what your API actually does. So how many people here have a, have some sort of spec that describes their entire API? Every resource. A few people, a few people. One of the most people when they build an API, for the first time, they don't think, oh, maybe I should have a spec for this. So this leads to problems because you, you don't have a single point of truth. There's not one document that tells you what your API does. Now when you make code changes, you know your API changes and that's okay. But your, your API code cannot be the single point of truth. You need to have some other document, or a series of documents that, that describes what your API does. I should log into your, go and look at your SDK, see one number of documentation, look at your docs, see something else. They, they, they should all be exactly the same. And if you don't have a single spec that describes what, what all of those things are supposed to be doing, it's going to be very hard to maintain. Otherwise, you're going to be up to three different things. Every time your API changes. So there's a few different options for how you might actually write a spec. There's JSON schema, there's Swagger, there's Ramel, there's API and a blueprint. And they all have to have different reasons why you might want to use that. So Ramel, which is becoming very popular, it's backed by what we call MuleSoft. Their API spec is basically just Ramel, in its own way with these, you know, forward slash unresources. And the nice thing about Ramel is that it's very flexible. If you use something like JSON schema, it's going to be more prescriptive. Ramel will let you pretty much do whatever you want. You can document any of API regardless of how it was done structurally. Which is really nice when you have an existing API that you need to document that you didn't create a spec for and don't really know how it works. JSON schema, this was created or was used heavily by the Muro team. They built a lot of tools to actually build these. The only problem with JSON schema is that it's very prescriptive. So if your API doesn't do things that JSON schema thinks that it should do, then you can't really document it. But if you're creating a new API from scratch it might be a good option for you. Swagger, most people know Swagger from the UI tools. Swagger is a great option. They have some great tools built. It's also one of the older spec languages out there. It was really one of the first ones that people started using and they've done a nice job. You know, downsides, it's very verbose. There's a lot of different parameters you have to add to it. On the other side, you have things like API and Blueprint. On the left-hand side there is what you enter. And on the right-hand side is what that generates. The right-hand side is the JSON schema representation of the Blueprint on the left. While this might be okay, it makes it hard to override things. It also just creates this magical land. Also, it's a giant server. You have these spec languages. Now you need to actually write one. There's two different extremes of how you might write any spec. You can either auto-generate it on the one hand or on the other hand you can write it by hand. Now, it's unlikely that you want to just sit down and actually write your entire spec now. That's going to take a long time and it's also going to just be really in the dots. It's likely that you're going to look at your docs and you're going to start writing some stuff and you're going to look at your code and see if your docs are right. The whole exercise of that is pretty challenging. Now, if you want it all auto-documented, well, that's okay. If you've ever seen Java docs, that's what those are. And they lack what I call a human element to them. They're what you decided to include at a developed time not when someone actually needs to use it. So the compromise is to generate a spec that is partially... that is either partially ungenerated by the code or it's something where you have tools that help you write. So there's two mindsets to this. The first is a partially code-generated spec and what this is is you build a tool that actually parses your code and gives you a spec from it. And then when you want to add things like lines for documentation, it just leaves those blank and handles the merge between. There's a couple of pre-built tools that actually undo that. If you use rape or Rails on zeroizers, there's a couple that can just read that. This is really easy when you're already writing your API with a tool that is prescriptive. That gives you a separate way of writing your API. If you're not using some sort of prescriptive tool, it's going to be a lot harder to actually parse your code to generate that spec. So on the other hand, you can build specs, which are ones where you're actually writing out the spec. But instead of just writing it by hand every time, you can build a lot of tools that will do that for you. So with Rails, similar to Rails Nu, you can use things like resource Nu. And you can build a generator. There's a lot better out there that will just generate a sample spec for you that you then need to fill in. This makes it easier to use, you can do a validation that way just to make it easier for you to write it by hand. In the example of one that I'm going to be building, we essentially just built a set of templates and you can just hand a resource name to it and boom, here's a bunch of resource files that I can go in and edit. If I want to add a sub-resource, the tool can just handle that by giving it like dash dash sub. While there are tools that are out there like this, you can write them yourself without much work. You probably already, if you were going to write something for most N-webs, you're probably doing a lot of cutting and pasting N-webs. So that becomes your template. That's all you need to actually go and copy. So once you have these schema files written and markup files written, this can be then converted into actual docs. So we run this one shell script that goes through all the files, it validates them, and actually converts them into HTML, of course, in one public folder. This is sort of a breakdown of what's actually happening. With these rental files, which you write up, we use a rental. We actually create these rental files from code, and then that code is combined with markup files, which are the tutorials, and then we turn that into our HTML. The rental, the rental is regular use just for SDKs. There are other elements to just taking, you know, spec files and converting them to our HTML. We use a left hand map, which handles all those tutorial files, and it handles taking the files that we have and turning them into a left hand map. So you see the JSON file on the left, that becomes what is on the right. This is unthemed. We have another tool that actually themes it all. And what ends up outputting is something like this. You have the left hand map on the left, and the markdown is on the right, and then each resource looks something like that. You take the bodies, all the example code, and spec itself, and actually generate documentation from that to get something so that it's pretty much a complete reference with anything that you could want. We first developed this by hand. So we would actually create each of these ages with HTML. And, you know, eventually we built these automated tools because that was hard to update, obviously, and a lot of work. So we found a template that worked for us, and then we built the tools to generate that template. Once you have a spec file, it's not that hard to create things like SDKs, depending on the language you choose. There's a lot of pre-built ones out there. Some of them are really good. Some of them are really bad. Typically, the ones that are better are ones that were created as its own SDK, and then the internals will pull that, and then a spec was actually put in. It just makes it feel more like an SDK you would be used to, not something that is really unprescriptive. If you want something like a client wrapper with a spec, they're not that hard to create, and those are going to be better and quality. The Render one's pretty good. It just creates JSON, and the Swagger code gen. Some of the SDKs that it generates are pretty good. Other ones of them are just broken. You look there, I'm sure you can see the front there, but it's hard. The major takeaways from this is we're taking our documentation as natural products. If your API is what people are consuming, that's what your product is. You need to invest in the tools to actually build the documentation to let people use that. If you never actually think of it like a product, you only think of it like, oh, we'll just write the documentation app there, maybe we'll put it in a Google Doc, and just share it. It just becomes overhead for you. You won't want to, and update it. And what that'll lead to is people won't want to use your on API. You've got to build the tools to do something like this. I found that Go's CLI is actually really good. It makes it really easy to build these, and also it's easy to share. So if you're a developer, you're not the one who's actually updating the documentation. You have maybe a VM or something that's, that is, I'm doing it. If you're using Go tools, then you can just share that saying, I don't need to know how to use Ruby or anything like that. But yeah, so hopefully you have a better understanding how you should be building your documentation. Any questions? No questions? Do you think you can owe it to your users to build clients in all sorts of languages, or do you owe it to your clients? The question was, do you think that you owe it to your clients to build clients in their language for them? I think that it depends. So if you have, if you're building something where it's going to be complicated for someone to use an existing, like just HMTV, then yeah, you should probably have some sort of client wrapper out there. They're not that hard to make. The problem is that if you don't from day one have those tools out, people might choose not to use your tool because someone else has a client for theirs. On the other side, you could build a really bad one. And so if you think you can do really well enough, I would say go for it and do it. We build all of ours for very light wrappers. In about two weeks, we build like four of them. And they're not that great, but they do enough. And they don't, they don't really have any magic in them. But if we hadn't done those, I think people would have been less likely to use our tool. Especially when you're on like a sales call or something like that. So I was like, well, do you have like a Python library? He said yes, yes we do. And it was not that great. You still get to check that box. Any other questions? Yes. Do you have any thoughts on creating good API documentation that outlines valid values for certain things that get sent in, especially if those values might be maintained by someone less technical who knows the data better that says, you know, you can send these values over here and that's what they mean, or this is what these codes mean, the amount of kind of things. Yeah. So the question was, do you have any advice for in summary in how to give your clients who are building your docs, giving them parameters that are, that they might not have actually generated themselves? Or like what's valid to pass it? More like let's say you say, tell me about this thing in your API call. And it has a couple of description codes that come back and what they mean. Oh, so it might actually be response codes and understanding. And not so much a pass fail, but more of a, you know, you say A123 means it's a green thing or, you know, like seven means it's. Gotcha. So how do you describe, so how, like, what sort of responses would look like and sort of how those get translated. We normally do them out just as HTML files, because like here is, we'll include links, because most people aren't looking for it in the call itself. So we have other pages that we look to where we describe what those response codes are and what they translate to. However, if you're, there might be a deeper issue. If you're returning codes, that first intermediate isn't going to know what they are. And that might be something that you would want to wrap in a client library or something like that. Pretty much sort of like an object where that, where you can actually give it a description to understand what it is. Yeah. But like most of the time, we just write states out. You don't automatically generate those, because normally there's not that many of them, for us at least, if there's a lot, you might need something else. But just being able to describe those and what they are. Any other questions? What are some of the biggest failures you've seen designing a build-maker? Do we pay API, what have you learned from that? Do we pay API specifically? So we, in our current version that people have access to, we have another version that will come out in the next few months. But the version that's up there right now, we've done a lot with, a lot of what's there is not quickly resourced and oriented and more surrounds. There's a lot of alias calls. And we've found that we either have people who really love them, or we have people, we love people who build your APIs, things that you can so easily use. And you have other people who try to combine them with other things and coming from more like a PayPal mindset. It's harder for them to understand. So in our next version, while we're keeping a lot of the alias calls, because people like them, there'll be more resource options to call the same things. That's probably one of the bigger things we've learned about a lot of what we use in our API. So I heard yesterday one of the best API stories, which was apparently if you call the National Weather Services, an API, it does geolocation on you, regardless of where your server is. So if your server has to be sitting in Virginia, they'll give you the weather for Virginia, even if that's not where you are. So that might be the most epic fail of people not understanding how APIs are used. Any other questions? Have you got any requests for which errors can possibly be from which endpoints and documentation for that next? So how have you solved that problem? Can you read the question? So certain endpoints are going to return certain errors sometimes. Different from other endpoints. Sort of like in a strongly connected language, you might have a froze law exception. Have you got any requests for that new API? So have you solved that problem? So explaining to a user how certain errors, what errors might be thrown by different endpoints. That's right. So we have one document that describes the error states that we might throw, so we try to keep it consistent. That's the first step, is trying to make sure that when an error gets thrown, it's thrown at least in a consistent way. So if you know how to handle it generally, you'll know what's going on. We run into a problem where there's a lot of errors that we can throw that we don't actually know what's going on. It's actually a problem like user credit card. So when you make a call with WePay, we're actually talking to like four different banks down the line, and any error in that flow could be a master card or whatever, could be causing the problem. So we try to handle it generally, and say, okay, so most people can handle it. We have like four or five different error states that we combine things down to. And if you get one of those, there's a way to handle it, which is mostly like you should retry, there's something wrong with the data, or like we don't know what's going on, you should probably call this, or like they should call their bank, one or the other. So I think that's the big thing, is just trying to simplify it down. And if you can't do that, I would just be really explicit in the docs about how to handle things, and perhaps giving someone like a pseudo code, like a case structure of what they might want to do. Not making me have to come up with a project myself is going to make me happy. Any other questions? Awesome. Thank you all for coming. Thank you.
 Thank you all for making the mistake of coming to my talk.  Hi everyone, I'm Shannon.  So my name is Scott.  I work for what we call the Mojite.  We're an API based payments company similar to Stripe.  We do payments for people like constant and contact, media.com,  and basically any credit run insane.  So my title is, Why Your API Product Will Fail.  As you might not know, if you want to get your talk on selected  and you want people to show up to it,  you should have something really click-by and ask for business.  So the title probably should be something more along the lines of  how to build an API tool in the business sector.  My name is Scott.  Some people confuse me for Taylor Swift.  Sorry about the confusion coming in.  I was also told that if I could just go down and occur,  people wouldn't be mean to me.  So today's agenda is what does good API toolings look like  and how do I build it in a scalable way?  How do I build it in a way where every time I launch a new version of my API,  I'm not freaking out?  Okay, so let's start with what is API toolings?  But before we get there, how many people have ever used an API before?  Most people, pretty much everyone.  How many people have used an API that's sucked?  How many ever used an API that did things that Dr. Jason said that it didn't do?  Yeah, a lot of people.  So what API tooling is meant to do when it's built well  is to rent things like that from a company.  So again, the consumers, that's us, need chance to use the MEPI  in the way that it was designed to be used.  Now remember that every time you use a MEPI, there was a developer,  just like us, perhaps someone even in this room,  who decided to write the dog on that, or wrote the actual MEPI.  So consider that, not that you should be sympathetic,  but that when you're doing it yourself, you don't have to do those same things.  So API tooling is essentially two things.  It's documentation that is reactable to a lot of API clients.  Some people call them SDKs, some people call them wrappers,  whatever you want to call them, they are the way that someone interacts with your API.  Now if they want to use a curl client, whatever,  but most people offer some sort of client-in-him library.  So that documentation can be further broken down into tutorials,  the actual reference docs, and the explanation and use cases of those API calls.  So we'll start with the tutorials.  How many people have ever, when they started using an API,  tried to jump into the reference docs,  you probably said, okay, how do we put this smallest thing that I actually do with this MEPI.  Give me a how-to guide.  So what does how-to-times do?  Because it needs to tell you what you're actually doing.  You've never used this on the API before, then you probably don't know.  You're probably going to need some detailed steps.  Steps that even perhaps the most junior person on your team  would be able to follow.  And also, I don't know about you, but I don't actually really like doing work.  I really just like to copy and paste stuff.  Ideally not off-stack and overflow.  Ideally like from your docs themselves.  I don't really know how to Google it, but make it easy for me.  Make it easy for me to just sort of copy and paste, get going,  because I don't really want to do work.  Oh no.  I don't know about you.  So here's an example of what a tutorial on what's like.  We should have some sort of explanation of what you're doing.  We should have some sort of example, use case for how this might be used.  And then before you actually just create a large own tutorial with lots of steps  and copy and paste, you should actually probably tell the person from a high level,  this is what we're actually doing.  Because likelihood is if I probably don't know, I'm actually a page note.  You might have a good title on it. You might not.  Just tell me, okay, before I get started, I have to sort of go,  wait, this isn't actually what I'm wanting to do.  Because most tutorials, they're very text heavy.  Don't make me read.  So with each step, don't just include the code.  Include some sort of like, this is what you're actually doing in this code.  While it should be obvious, your code should be at least decent.  It might not be that obvious to someone who's I'm assuming.  So beyond tutorials, once you're actually using an app,  likelihood is you're going to do something a little bit different.  Something that may mean the tutorial writer didn't come up with.  And that's what we're going to talk about reference.  So these are the docs where you see all the calls and everything that a API does.  So the simplest API call is, I'm going to send you an ID.  You're going to send me an object back.  It's a very simple get.  So in this get, you're going to want to see, okay,  so what's the parameters that I actually need to pass?  Is it required? Do I need that?  Why not just be one? It might be a few.  What is the type of that?  And then give me an example.  Well, this one here is really basic.  More complex stuff.  That stuff is actually really neat.  And then once that stuff is actually returned,  you need to tell me what is it that you actually just sent?  I don't know your app. I don't know the object structure.  But you bring down for me what each of those parameters is  and how I'm supposed to use it.  And in addition to that,  it's really nice when you give me like a JSON example to work with.  If I don't have some sort of example data structure  that I can call and paste into my code and actually start playing with,  it might, well, like you're like, well, you can just make a call  and then you can play with that.  Not every call to your API can I immediately make.  I might need some actual data in there first.  So let me figure out how I'm supposed to play with it  before I actually have to make a call.  So in your reference docs,  make sure that every resource is well undocumented.  It's okay to visually duplicate things in docs  because one of the worst things you can do is give me like a bunch of links to other pages  and to actually understand what your, what an API call is doing.  You're making me jump around.  You're making me access three, four, five files to do one thing.  And that's no fault.  Also the requests and the response parties,  make sure that I can copy and paste those.  Make sure that I can actually see what those are.  And hide those from.  Don't make me make calls just to see what your API does.  And for each parameter in those,  make sure that those are well documented.  Otherwise, you're going to have people emailing you or a support team asking,  okay, what does this parameter do?  It's not consistent.  What's the problem?  So explain what each of those are and how these use them.  Now to actually build these sorts of docs,  you need to first figure out,  you first need to know what your API actually does.  So how many people here have a,  have some sort of spec that describes their entire API?  Every resource.  A few people, a few people.  One of the most people when they build an API,  for the first time, they don't think,  oh, maybe I should have a spec for this.  So this leads to problems because you,  you don't have a single point of truth.  There's not one document that tells you what your API does.  Now when you make code changes,  you know your API changes and that's okay.  But your, your API code cannot be the single point of truth.  You need to have some other document,  or a series of documents that,  that describes what your API does.  I should log into your, go and look at your SDK,  see one number of documentation,  look at your docs, see something else.  They, they, they should all be exactly the same.  And if you don't have a single spec that describes  what, what all of those things are supposed to be doing,  it's going to be very hard to maintain.  Otherwise, you're going to be up to three different things.  Every time your API changes.  So there's a few different options  for how you might actually write a spec.  There's JSON schema, there's Swagger, there's Ramel,  there's API and a blueprint.  And they all have to have different reasons  why you might want to use that.  So Ramel, which is becoming very popular,  it's backed by what we call MuleSoft.  Their API spec is basically just Ramel,  in its own way with these, you know, forward slash unresources.  And the nice thing about Ramel is that it's very flexible.  If you use something like JSON schema,  it's going to be more prescriptive.  Ramel will let you pretty much do whatever you want.  You can document any of API  regardless of how it was done structurally.  Which is really nice when you have an existing API  that you need to document  that you didn't create a spec for  and don't really know how it works.  JSON schema, this was created  or was used heavily by the Muro team.  They built a lot of tools to actually build these.  The only problem with JSON schema  is that it's very prescriptive.  So if your API doesn't do things  that JSON schema thinks that it should do,  then you can't really document it.  But if you're creating a new API from scratch  it might be a good option for you.  Swagger, most people know Swagger from the UI tools.  Swagger is a great option.  They have some great tools built.  It's also one of the older spec languages out there.  It was really one of the first ones that people started using  and they've done a nice job.  You know, downsides, it's very verbose.  There's a lot of different parameters  you have to add to it.  On the other side, you have things like API and Blueprint.  On the left-hand side there is what you enter.  And on the right-hand side is what that generates.  The right-hand side is the JSON schema representation  of the Blueprint on the left.  While this might be okay,  it makes it hard to override things.  It also just creates this magical land.  Also, it's a giant server.  You have these spec languages.  Now you need to actually write one.  There's two different extremes of how you might write any spec.  You can either auto-generate it on the one hand  or on the other hand you can write it by hand.  Now, it's unlikely that you want to just sit down  and actually write your entire spec now.  That's going to take a long time  and it's also going to just be really in the dots.  It's likely that you're going to look at your docs  and you're going to start writing some stuff  and you're going to look at your code  and see if your docs are right.  The whole exercise of that is pretty challenging.  Now, if you want it all auto-documented,  well, that's okay.  If you've ever seen Java docs, that's what those are.  And they lack what I call a human element to them.  They're what you decided to include at a developed time  not when someone actually needs to use it.  So the compromise is to generate a spec  that is partially...  that is either partially ungenerated by the code  or it's something where you have tools that help you write.  So there's two mindsets to this.  The first is a partially code-generated spec  and what this is is you build a tool  that actually parses your code  and gives you a spec from it.  And then when you want to add things like lines for documentation,  it just leaves those blank and handles the merge between.  There's a couple of pre-built tools that actually undo that.  If you use rape or Rails on zeroizers,  there's a couple that can just read that.  This is really easy when you're already writing your API  with a tool that is prescriptive.  That gives you a separate way of writing your API.  If you're not using some sort of prescriptive tool,  it's going to be a lot harder to actually parse your code  to generate that spec.  So on the other hand, you can build specs,  which are ones where you're actually writing out the spec.  But instead of just writing it by hand every time,  you can build a lot of tools that will do that for you.  So with Rails, similar to Rails Nu,  you can use things like resource Nu.  And you can build a generator.  There's a lot better out there  that will just generate a sample spec for you  that you then need to fill in.  This makes it easier to use,  you can do a validation that way  just to make it easier for you to write it by hand.  In the example of one that I'm going to be building,  we essentially just built a set of templates  and you can just hand a resource name to it  and boom, here's a bunch of resource files that I can go in and edit.  If I want to add a sub-resource,  the tool can just handle that by giving it like dash dash sub.  While there are tools that are out there like this,  you can write them yourself without much work.  You probably already,  if you were going to write something for most N-webs,  you're probably doing a lot of cutting and pasting N-webs.  So that becomes your template.  That's all you need to actually go and copy.  So once you have these schema files written  and markup files written,  this can be then converted into actual docs.  So we run this one shell script  that goes through all the files, it validates them,  and actually converts them into HTML,  of course, in one public folder.  This is sort of a breakdown of what's actually happening.  With these rental files, which you write up,  we use a rental.  We actually create these rental files from code,  and then that code is combined with markup files,  which are the tutorials,  and then we turn that into our HTML.  The rental, the rental is regular use just for SDKs.  There are other elements to just taking, you know,  spec files and converting them to our HTML.  We use a left hand map, which handles all those tutorial files,  and it handles taking the files that we have  and turning them into a left hand map.  So you see the JSON file on the left,  that becomes what is on the right.  This is unthemed.  We have another tool that actually themes it all.  And what ends up outputting is something like this.  You have the left hand map on the left,  and the markdown is on the right,  and then each resource looks something like that.  You take the bodies, all the example code,  and spec itself, and actually generate documentation from that  to get something so that it's pretty much a complete reference  with anything that you could want.  We first developed this by hand.  So we would actually create each of these ages with HTML.  And, you know, eventually we built these automated tools  because that was hard to update, obviously, and a lot of work.  So we found a template that worked for us,  and then we built the tools to generate that template.  Once you have a spec file,  it's not that hard to create things like SDKs,  depending on the language you choose.  There's a lot of pre-built ones out there.  Some of them are really good.  Some of them are really bad.  Typically, the ones that are better are ones that were created  as its own SDK, and then the internals will pull that,  and then a spec was actually put in.  It just makes it feel more like an SDK you would be used to,  not something that is really unprescriptive.  If you want something like a client wrapper with a spec,  they're not that hard to create,  and those are going to be better and quality.  The Render one's pretty good.  It just creates JSON, and the Swagger code gen.  Some of the SDKs that it generates are pretty good.  Other ones of them are just broken.  You look there, I'm sure you can see the front there,  but it's hard.  The major takeaways from this is  we're taking our documentation as natural products.  If your API is what people are consuming,  that's what your product is.  You need to invest in the tools  to actually build the documentation to let people use that.  If you never actually think of it like a product,  you only think of it like,  oh, we'll just write the documentation app there,  maybe we'll put it in a Google Doc, and just share it.  It just becomes overhead for you.  You won't want to, and update it.  And what that'll lead to is people won't want to use your on API.  You've got to build the tools to do something like this.  I found that Go's CLI is actually really good.  It makes it really easy to build these,  and also it's easy to share.  So if you're a developer,  you're not the one who's actually updating the documentation.  You have maybe a VM or something that's,  that is, I'm doing it.  If you're using Go tools,  then you can just share that saying,  I don't need to know how to use Ruby or anything like that.  But yeah, so hopefully you have a better understanding  how you should be building your documentation.  Any questions?  No questions?  Do you think you can owe it to your users to build clients in all sorts of languages,  or do you owe it to your clients?  The question was, do you think that you owe it to your clients  to build clients in their language for them?  I think that it depends.  So if you have, if you're building something  where it's going to be complicated for someone to use an existing,  like just HMTV,  then yeah, you should probably have some sort of client wrapper out there.  They're not that hard to make.  The problem is that if you don't from day one have those tools out,  people might choose not to use your tool  because someone else has a client for theirs.  On the other side, you could build a really bad one.  And so if you think you can do really well enough,  I would say go for it and do it.  We build all of ours for very light wrappers.  In about two weeks, we build like four of them.  And they're not that great, but they do enough.  And they don't, they don't really have any magic in them.  But if we hadn't done those,  I think people would have been less likely to use our tool.  Especially when you're on like a sales call or something like that.  So I was like, well, do you have like a Python library?  He said yes, yes we do.  And it was not that great.  You still get to check that box.  Any other questions?  Yes.  Do you have any thoughts on creating good API documentation  that outlines valid values for certain things that get sent in,  especially if those values might be maintained by someone less technical  who knows the data better that says, you know,  you can send these values over here and that's what they mean,  or this is what these codes mean, the amount of kind of things.  Yeah.  So the question was, do you have any advice for in summary  in how to give your clients who are building your docs,  giving them parameters that are,  that they might not have actually generated themselves?  Or like what's valid to pass it?  More like let's say you say, tell me about this thing in your API call.  And it has a couple of description codes that come back  and what they mean.  Oh, so it might actually be response codes and understanding.  And not so much a pass fail, but more of a, you know,  you say A123 means it's a green thing or, you know,  like seven means it's.  Gotcha.  So how do you describe, so how, like,  what sort of responses would look like  and sort of how those get translated.  We normally do them out just as HTML files,  because like here is, we'll include links,  because most people aren't looking for it in the call itself.  So we have other pages that we look to  where we describe what those response codes are  and what they translate to.  However, if you're, there might be a deeper issue.  If you're returning codes,  that first intermediate isn't going to know what they are.  And that might be something that you would want to wrap  in a client library or something like that.  Pretty much sort of like an object where that,  where you can actually give it a description  to understand what it is.  Yeah.  But like most of the time, we just write states out.  You don't automatically generate those,  because normally there's not that many of them,  for us at least, if there's a lot, you might need something else.  But just being able to describe those and what they are.  Any other questions?  What are some of the biggest failures you've seen  designing a build-maker?  Do we pay API, what have you learned from that?  Do we pay API specifically?  So we, in our current version that people have access to,  we have another version that will come out in the next few months.  But the version that's up there right now,  we've done a lot with, a lot of what's there  is not quickly resourced and oriented and more surrounds.  There's a lot of alias calls.  And we've found that we either have people who really love them,  or we have people, we love people who build your APIs,  things that you can so easily use.  And you have other people who try to combine them  with other things and coming from more like a PayPal mindset.  It's harder for them to understand.  So in our next version, while we're keeping a lot of the alias calls,  because people like them,  there'll be more resource options to call the same things.  That's probably one of the bigger things we've learned  about a lot of what we use in our API.  So I heard yesterday one of the best API stories,  which was apparently if you call the National Weather Services,  an API, it does geolocation on you,  regardless of where your server is.  So if your server has to be sitting in Virginia,  they'll give you the weather for Virginia,  even if that's not where you are.  So that might be the most epic fail  of people not understanding how APIs are used.  Any other questions?  Have you got any requests for which errors  can possibly be from which endpoints and documentation for that next?  So how have you solved that problem?  Can you read the question?  So certain endpoints are going to return certain errors sometimes.  Different from other endpoints.  Sort of like in a strongly connected language,  you might have a froze law exception.  Have you got any requests for that new API?  So have you solved that problem?  So explaining to a user how certain errors,  what errors might be thrown by different endpoints.  That's right.  So we have one document that describes the error states  that we might throw, so we try to keep it consistent.  That's the first step,  is trying to make sure that when an error gets thrown,  it's thrown at least in a consistent way.  So if you know how to handle it generally,  you'll know what's going on.  We run into a problem where there's a lot of errors  that we can throw that we don't actually know what's going on.  It's actually a problem like user credit card.  So when you make a call with WePay,  we're actually talking to like four different banks  down the line, and any error in that flow  could be a master card or whatever,  could be causing the problem.  So we try to handle it generally,  and say, okay, so most people can handle it.  We have like four or five different error states  that we combine things down to.  And if you get one of those, there's a way to handle it,  which is mostly like you should retry,  there's something wrong with the data,  or like we don't know what's going on,  you should probably call this,  or like they should call their bank, one or the other.  So I think that's the big thing,  is just trying to simplify it down.  And if you can't do that,  I would just be really explicit in the docs  about how to handle things,  and perhaps giving someone like a pseudo code,  like a case structure of what they might want to do.  Not making me have to come up with a project myself  is going to make me happy.  Any other questions?  Awesome. Thank you all for coming.  Thank you.
Why_Your_New_API_Product_Will_Fail_0_47.png Why_Your_New_API_Product_Will_Fail_48_155.png Why_Your_New_API_Product_Will_Fail_156_299.png Why_Your_New_API_Product_Will_Fail_300_1559.png Why_Your_New_API_Product_Will_Fail_1560_1619.png Why_Your_New_API_Product_Will_Fail_1620_1931.png Why_Your_New_API_Product_Will_Fail_1932_3695.png Why_Your_New_API_Product_Will_Fail_3696_4643.png Why_Your_New_API_Product_Will_Fail_4644_5399.png Why_Your_New_API_Product_Will_Fail_5400_5447.png Why_Your_New_API_Product_Will_Fail_5448_5507.png Why_Your_New_API_Product_Will_Fail_5508_5567.png Why_Your_New_API_Product_Will_Fail_5568_5615.png Why_Your_New_API_Product_Will_Fail_5616_5687.png Why_Your_New_API_Product_Will_Fail_5688_7703.png Why_Your_New_API_Product_Will_Fail_7704_8543.png Why_Your_New_API_Product_Will_Fail_8544_10979.png Why_Your_New_API_Product_Will_Fail_10980_11771.png Why_Your_New_API_Product_Will_Fail_11772_12131.png Why_Your_New_API_Product_Will_Fail_12132_12695.png Why_Your_New_API_Product_Will_Fail_12696_13367.png Why_Your_New_API_Product_Will_Fail_13368_15107.png Why_Your_New_API_Product_Will_Fail_15108_16127.png Why_Your_New_API_Product_Will_Fail_16128_17027.png Why_Your_New_API_Product_Will_Fail_17028_17747.png Why_Your_New_API_Product_Will_Fail_17748_20123.png Why_Your_New_API_Product_Will_Fail_20124_20627.png Why_Your_New_API_Product_Will_Fail_20628_20711.png Why_Your_New_API_Product_Will_Fail_20712_20855.png Why_Your_New_API_Product_Will_Fail_20856_21239.png Why_Your_New_API_Product_Will_Fail_21240_22031.png Why_Your_New_API_Product_Will_Fail_22032_24359.png Why_Your_New_API_Product_Will_Fail_24360_24467.png Why_Your_New_API_Product_Will_Fail_24468_24815.png Why_Your_New_API_Product_Will_Fail_24816_26687.png Why_Your_New_API_Product_Will_Fail_26688_31571.png Why_Your_New_API_Product_Will_Fail_31572_44519.png Why_Your_New_API_Product_Will_Fail_44520_44579.png Why_Your_New_API_Product_Will_Fail_44580_44627.png Why_Your_New_API_Product_Will_Fail_44628_44675.png Why_Your_New_API_Product_Will_Fail_44676_44864.png