Readme.io, one of the services that has greatly simplified the process of documenting technologies like APIs, is taking its popularity with API providers to the next level with a new offering called Build. Working off its tradition of simplicity, Build simplifies the design, provisioning and consumption of APIs by taking the same files that drive readme.io's auto-documentation capability and extending their functionality in a way that rather remarkably results in fully functional APIs. Any required data typing or validation is automatically applied.
But Build does not stop there. Not only does it auto-generate the documentation and auto-provision the API, it also simplifies developer consumption of the API by auto-generating pre-built cut-n-paste consumption samples that include a sample command line interface entry, sample code for Node, Python, Ruby and PHP, and an integration for Slack. The Slack integration in particular is one of the more interesting features of Build. The idea is that with relatively minimal background in coding, a non-technical person could, with little effort, create a service, put an API on it, and then make that service available to an entire organization's instance of Slack.
Speaking to readme.io's culture of simplicity, company founder and CEO Greg Koberger (who sat with ProgrammableWeb for the interview and video demonstration embedded below) said "I think that people just want to be able to build stuff and Javascript is a pretty easy language to learn because there is so much [tutorial material] out there. And I would love to be in a world where a non-technical or semi-technical person could build a really quick app." Koberger sees Build extending to other chat bot-like infrastructures; Amazon's Alexa for example. While Build auto-generates several consumption types (CLI, languages, etc.), the code that makes the API do whatever it's designed to do is written in Javascript. In the demo that's embedded below, Koberger launches a simple API that multiplies two numbers and returns the result.
Something else that Build handles very elegantly is the way in which it naturally pulls API developers and consumers together into a collaborative context for perfecting the API and ironing out any bugs. Consuming developers are automatically notified of failures via email and a logging capability, the latter of which also auto-creates collaborative Github-like issues where team members can drive to the best resolution.
Build does not include any industrial strength API management capabilities and as such, is targeted at smaller businesses, startups, and maybe even enterprise developers working on proofs-of-concepts. Also, in terms of the various consumption samples it offers, noticeably missing is the sample code for Android (Java or Kotlin) and iOS (Swift or Objective C) developers. Koberger says they're coming soon. Same for an on-premises version of Build for organizations looking to keep their Build-based APIs behind their corporate firewalls.
Build comes with a relatively generous tier of free usage for public APIs based on number of API calls per month. But for non-public APIs (ones mainly intended for the provider's consumption only) and APIs that exceed the free tier's threshold of 1 million calls, there are nominal fees involved.
To really get an idea of how Build works, be sure to watch, listen to, or read the interview (all formats available below)
Video of Greg Koberger Interview and Demo of readme.io Build
Editor's Note: This and other original video content (interviews, demos, etc.) from ProgrammableWeb can also be found on ProgrammableWeb's YouTube Channel.
Audio-Only Version of Greg Koberger Interview and Demo of readme.io Build
Editor's note: ProgrammableWeb has started a podcast called ProgrammableWeb Radio. To subscribe to the podcast, point your podcatcher to its RSS feed or tune into our station on SoundCloud.
Full Transcript of Greg Koberger Interview and Demo of readme.io Build
Editor's note: This full transcript includes time codes at one minute intervals. If you click on the time codes, it will take you to directly to that spot in the video on YouTube. We hope you like this feature.
David Berlind: Hi, I'm David Berlind, editor in chief of ProgrammableWeb, and we're here today with Greg Koberger. He is the founder of ReadMe.io. For those of you not familiar with ReadMe.io, they have a bit of a history when it comes to hosting documentation. A lot of API providers like to use ReadMe.io to host their documentation, but I'll defer to you Greg. Welcome, first of all, to our show.
Greg Koberger: Thanks.
David: Yeah, it's great to have you here. The first thing I really want to ask is, give me a little bit of the history of ReadMe.io before we get into what it is you're announcing this week.
Greg: Sure. ReadMe is, like you mentioned, a company that [has] a documentation platform for APIs. We've got a bunch of really cool companies using us, a bunch of smaller companies, bunch of start-ups, bunch of big companies. Box and Lyft and Intercom and a bunch of companies use us for their API documentation. We got started about three years [00:01:00] ago, [when] we launched. Our anniversary is next week, three year anniversary. And we kind of started ... The goal was always to get as far and deep into APIs as possible. Our mindset was always that the documentation isn't just a static, boring thing that you push a static site. It should be interactive, it should know about the user, it should adapt and learn about the user. It shouldn't just be a GitHub pages repo, where there's just paragraphs of text. You need that stuff of course. We always believe that the API documentation is really the interface for the API. We've worked to make API documentation as interactive as you'd expect from any another website.
David: Okay. Things have been going pretty well, about how many API providers do you think, today, are using your website as the host of their documentation?
Greg: Sure, so we have about 3,000 paying companies [00:02:00] and then we've got about 10,000 total of open source, etc, projects. We do everything, we do about half of those are APIs. The other half are product documentation and other types of documentation. So I guess, to put it another way, about 1,500 APIs are hosted on us.
David: Any customers of note? Like big customers that we would recognize?
Greg: Sure. Some of the big ones are like, Box uses us for their documentation, their API documentation. Lyft's API documentation is all on us. Intercom, Trello, a few Atlassian projects, Zenefits, we've been lucky we've been able to work with some really cool, big companies. Just some bigger ones like IBM, Microsoft uses [us] for stuff, tons of little start-ups all over. I'd say we kind of run the gambit of big, big, big companies. Really cool medium sized companies and a ton of small companies.
David: Now documentation is talked about [00:03:00] ad-nauseum in the various circles of the API economy. Everybody always talks about how important it is to engage developers with very compelling documentation. And of course other features that a lot of developer, evangelists and API providers will use to hook and attract developers. What would you say are ... You've been in this space now for about three years, as you've said. What would you say are some of the key factors to offering really compelling documentation?
Greg: Sure. I think one of the best and worst things to happen to APIs and API documentation is Stripe. It's because everyone absolutely loves Stripe. And rightfully so. They really knocked it out of the park with their documentation. And that's a good thing. The bad thing, and this is not their fault whatsoever, is that I think people take the wrong thing away from Stripe's documentation. They see it, they see the three common layout, think this is pretty, and think that's what makes good API [00:04:00] documentation.
And attractiveness is, of course, important. You wouldn't want ugly anything. But I think the reason why Stripe's and Twilio I think are the two that I get the most feedback on, are the gold standard of documentation, it's not because they are pretty or anything like that, or because they have tons of paragraphs of text, it's because it's so well integrated. They're not static. They know exactly who you are, they know your API keys, they know the last call you made, it's all very well integrated. You can play around with it.
So I think things that are really important, you definitely need a reference guide. That is like that ... you've seen those, those gigantic three column layout pages, just like Stripe's, with the black columns on the right side. And I think you definitely need that, but I think that too many people stop there. And for me, that's kind of like handing someone a dictionary and saying, "Learn English." It's supposed to be a reference guide. It's not supposed to be the documentation.
I think what people really need is, or documentation needs is it needs a lot more than just that. It needs ... you know, [00:05:00] the things compared to documentations. Like Stack Overflow. Not their documentation product, just their questions and answers. Because, I don't want to put words in your mouth, but if you have a problem with an API and you Google it, and you see the official site, and then you see right below it, a very similar question on Stack Overflow, I click Stack Overflow. And I think, support forums, things like that, are really important to documentation, to have those integrated in. It's really important.
And I think example is the biggest thing. Again, not to put words in your mouth, what I do at least is when I go to a site, I scroll down to find the code snippets. And copy and paste it and just kind of like pricing myself a lot of times I read paragraphs with text, but I don't. So I think interactive API documentation where you can actually see examples and copy and paste. Nobody wants to go to a reference guide and see the URL is this, the params are this, and have to in their own language, Python, Rails, etc., you know, reassemble into a call and then trying to get the call. It's just really frustrating.
Every evening we measure [00:06:00] the MVC, the Minimum Viable Call, the time to that. So from, let's say you want to use a random API, like the most, the things most valuable to us is getting you from signing up to use the API to making some sort of innocuous call. Doesn't really matter what it is. But it should be kind of important. It should show that you did something. That's kind of important. Your API key is working properly. You have the SDK, if there is an SDK, is it set up properly? Once you get that, it's kid of gravy [00:06:30] from there. But I think too many companies leave out that onboarding flow. How do we get David from ... yeah, it seems like a cool API, to ... "Oh" I posted a tweet, or I got a list of my friends, or I updated my status on this site, or whatever. In as little time as possible. After that, you'll be more inclined to dig through the documentation and learn more and figure out more.
In my mind, there's nothing worse than using an API and just seeing a thousand endpoints, a gigantic page that takes [00:07:00] two minutes to load and it's alphabetically ordered, and it's just endpoints like /user. And to create these, you have to do "POST /user." I'm like, that makes sense to you and I, but it just gets tiring to ...
David: To the rest of the world, yeah.
Greg: Yeah. And even to me it doesn't make sense. I mean, it makes sense, but you have to think about it and it's not natural, I don't think.
David: I think one of the things that I run into, which I still haven't seen anybody really fix this particular problem, is sometimes you run into APIs that are best implemented on the server side. Which means that the, within the documentation environment, it's a little more difficult to offer some sort of interactive capability for testing that API. You have to launch a Node environment, or something like that. I'm surprised Heroku, who you're familiar with, hasn't gone and said, hey, we're going to provide this sort of point and click sandbox for API onboarding.
Greg: So I'm here to promote my company, but [00:08:00] I'm going to keep promoting Stripe, I guess. Stripe recently bought a company called Tonic and renamed it to RunKit. It's pretty cool, you should check it out. That's exactly what it is. You can play around with it in line, it's so much easier. Because it's so nice to know that it works. To just be able to click Go, and just get a response back and be like, "Oh, that was easy."
Yeah, I'm with you 100 percent. And I don't, we don't, unfortunately we don't really do that either, for ReadMe, probably should get on that. We fake it as much as we can. In the sense that you can see a Python code and you can run it. It's not actually running Python, but as far as you're concerned, it could be.
David: It sort of virtualizes it.
Greg: Yeah, it would.
David: Just going back to you talking about how Stripe and Twilio are used as the poster children. Weren't they really preceded by Slate, which really is the predecessor to that three column format?
Greg: I can't answer that, because. Well, let me rephrase that. The understanding that I've always had was that it wasn't Slate, [00:09:00] it was CoffeeScript was the inspiration for that three column layout. And CoffeeScript had a, it was a little bit different, they had all the code and the code was annotated, but it was that three column thing. And the way I heard the story, and I don't know if it's true or not, was that came from, that's where they got it from. And I think that's Slate was response to that. I think Slate came after that.
David: Yeah. Slate was came after that. Yeah, that's true. But I mean Slate was really the first one that established a separate code base that you, anybody could go grab from GitHub and you just go do, right.
Greg: Oh yeah. Yep.
David: Is Expedia the one that put ...
Greg: TripIt. It's TripIt.
David: TripIt, TripIt. That's right. I knew it was one of the travel companies. Okay. So there you go.
We've taken a walk down memory lane. You guys are here today to announce the next big thing from ReadMe.io, so let's hear about it.
Greg: Yeah, so this is, so we talked about the current product. Which is going to continue to be the product that we use, that we spend a lot of time [00:10:00] on, we still love it. But one thing we started to notice is that APIs are getting simpler and simpler and most APIs on us are attached to a company. They're attached to Lyft, or Box or a big company. It's like a company API, if you go on the Web I'm sure you see there's not a ton of really compelling APIs that aren't backed by a big brand name. For whatever reason. And I think that is going to change over the next few years, for a lot of reasons.
So we are building something, it's very well integrated with the current product, but it's also very different, called ReadMe Build. Which is a way to leverage the documentation of your API to build it. It's a natural progression, because like we talked before, I think that the biggest thing that makes docs really good is how well integrated it is with the API.
If you can print out the docs and it's just as good and static, that means that ... let's say that you're making a call to an API and keep getting errors, and you don't know why. When you go to the docs, you want to know why. You want to know, "Oh the API is just down, it's not [00:11:00] my fault. I'll try again in a few hours." Or you want to know that, "Oh David, unfortunately your credit card is expired. Click this link to, it was a rate-limiting problem, click this link to pay.", or whatever. Or you want to know that you messed something up, you want to be able to debug it, maybe they changed something, who knows.
But my opinion is that, good API documentation should know when something's wrong, it should know when something's right, they should know when it's your first time using it and do something a little bit different. Things like that.
Build is, works well for ReadMe, but it's a simple way to build APIs. That's not the hard part. The cool part is that, how well integrated it is with the docs. How well the docs now know about you.
David: So let me stop you there for one second. You say "build APIs." And of course, there's ... for years, we've discussed something called the API lifecycle. Which consists of several different phases that stretch from planning and trying to strategize just exactly what it is you are going to do. Then designing the API, [00:12:00] that addresses that plan. And end up launching API, hosting it, governance, managing things like API keys and security, mapping it back to your back-end security. Applying Oauth, and so on.
So, analytics, managing all the users when you're issuing these keys. That sort of stuff. Which parts of that lifecycle are you addressing with this product called Build?
Greg: So as companies get bigger, obviously the lifecycle becomes more and more intricate. This is definitely aimed at either smaller companies, or microservices, or developers on the weekend, things like that. In theory, it does most of that. Obviously not nearly as well as the companies that do it well. But the whole goal is to do all of it and it gets you from idea [00:13:00] to having API keys and all that stuff, logging and all of that, within two minutes.
Do you want me to do a quick demo and show you what it looks like to build an API?
David: That would be great. Let's go ahead, let's go right into the demo. You're going to have to flip us into the screen sharing mode, but that would be great.
Greg: Okay, you want me to quick flash yourself, but okay.
David: Yep.
Greg: Okay. So this is ReadMe Build, are you able to see us?
David: I sure am. Yep.
Greg: Perfect. So the whole concept is, what would it be like if APIs were as, just took away everything that wasn't completely necessary. So it's really as easy to get started as typing "npm install api –g" and then "api init."
Wrong way. There we go. Okay. Can you see the terminal right now?
David: I can.
Greg: Perfect. Okay. So we are in a new ... there's nothing in this directory or whatever. We're going to type "api init". It's going to walk us right through ...
David: We've already installed ...
Greg: Yes.
David: Yeah. Okay.
Greg: Yep. So you have to type "npm install api –g" to get started. [00:14:00] But once you do that, you can type "api init". So you type "api init", it's going to ask us for the service name. We're going to call it PW for ProgrammableWeb. A new version .001. Now we're going to do a really simple one. We're going to do, we'll call it multiply. We're just going to multiply two numbers together. You can use a database, stuff like that, but we're not going to do that for now.
So it sets it up. So now we have a few files in here. For anyone that's familiar with server lists, or Lambda, or stuff like that, it's definitely very similar to that. The only big difference is that the focus for us is on the end consumer eventually, not the creation of the API. You'll understand what that means in a few minutes.
So now I'm going to edit this multiplier file. Which, okay. So the comments are actually important in this. This is where all the documentation is done. It lives right ... so you said the API lifecycle, we kind of threw it all in one file. For whatever reason, my computer does not like that. Okay.
So we are going to type "multiply two numbers"[00:15:00]. And then we're just going to have an X, our first number. I'll do Y. It's very similar to JavaDocs or even like Swagger, something like that. But it's right in line. And Result.
So, there's that. We're going to write this in Node ...
David: That was a comment, though. Right? It looks like you're using. We're in Javascript here and that's just basically a set of comments that you wrote.
Greg: Yep.
David: And is that something that your documentation capability picks up on? Like if you ...
Greg: Yes.
David: Okay.
Greg: So there's a few things. It's great for ... on the one hand, it's good for just anyone editing the file to know what's going in, what's coming out, stuff like that. But eventually we'll see when we deploy it, the information I just [00:16:00] typed out will be the documentation. It will also take care of validation. It will make sure that you have the right values being passed in, and the right type. Stuff like that. You can see that I did X equal to 5, and Y is equal to 3. Those are the defaults, so you don't pass those in, that's what that is.
David: Okay.
Greg: So we're done here.
David: What's the export. That's the code right there, we go back to that and take a look at that real quick?
Greg: Yep. Of course.
David: Because that's the actual code, right? So ...
Greg: Yep. Yep. So module exports is a node, that's the way that node, you say this is it. This is the boiler plate code that shows up. We do have the API modules, so you also can type it out as "api.create('multiply'...", and it's a little more ... so this is the more Nodey way. And then we have a more easy to understand kind of way.
David: Okay.
Greg: And so I went the Nodey way, because that's just the [00:17:00] way that popped up first.
David: That's just the validation, you're just checking to see that there's data, there?
Greg: So, we're only, it's a really simple API, obviously this should not be an API because we're just multiplying two numbers, but ...
David: Yeah. No, no, no, I get it. I just, you know, so for people who are watching, they're like, "Well, what's that?", for anybody who doesn't understand what's going on here. And all that is, is an If statement that checks the contents of X and Y to make sure that there's something in there and then the, error dialogue that throws it if there's a validation error.
Greg: Yeah.
David: So, and then ... okay.
Greg: There's two options. It can either be an error, or a success. So if it's an api.error, then we know that's its a ... the API is going to take care of all the standardized responses, making sure it's returned properly. And if it's a success, we know it's returning a number and it's going to be the result.
David: Just doing the math there.
Greg: Yep. Exactly.
David: Okay. Very good.
Greg: So what we are doing now, is we can actually run it locally, just test it out.
David: Sure.
Greg:[00:18:00] So we type "api local multiply X=3". And I'm going to leave Y out, because we're going to get an error. This is going to be a mistake on purpose. Okay, so we got an error. Validation error, you must provide all required fields.
David: Okay.
Greg: I'm going to try this again. We'll [add] "Y=5" it's going to do math quick. 15. Perfect. Okay, so I'm pretty happy with this. My API as far as I'm concerned, good to go. And I want you to use it now. So I'm just going to type "api deploy" and it's going to ask me a few questions, we're going to make it a free public API, all APIs built on Build are free as long as they're public. If you want to use it internally, then it will cost money, but it's free.
And I got a little URL here. So I'm going to click this URL. And we're going to see our documentation. So this was built kind of on the fly. This is our API we just built. There's a bunch of different ways to consume it. On the command line, on Node, Python, with Slack, we have a Google Sheets integration. Because I don't really think that APIs need to be consumed [00:19:00] by someone who's writing Python for example. Or Rails. There's a lot of really great use cases for APIs that don't involve it being used by someone who is a programmer, who has [Computer Science] degree.
David: Now let me stop you there and just ask a question. So for security reasons, some APIs are purely designed to be consumed with a server side language. Because we want to protect some of the information that's crossing over the wire between the consumer of the API, like the server side system and the API itself, as opposed to, let's say, in a browser. Do I have some flexibility over what it shows me here?
Greg: Sure.
David: Can I restrict it to just the languages I want it to show? And most notably missing, of course, would be some of the mobile consumption vehicles such as Swift, Objective C and Android Java. So ...
Greg:[00:20:00] Yeah. So I actually think the front end ones, that you said, JavaScript, non-Node Javacript, and then Swift and Java for Android, are three of the coolest use cases for this. That being said, we haven't gotten those ready to go yet, just because like you also mentioned, the security is kind of tough. Because they're front end languages, it makes it really hard to lock them down.
So for this, we don't have our front end stuff yet. We're going to release them next few weeks. We can actually consume it from the front end. For right now, it's back end only. For better or for worse.
David: Very good.
Greg: I think that they're ... because I think that people just want to be able to build stuff and Javascript is a pretty easy language to learn. Because there is so much out there. And I would love to be in a world where a non-technical or semi-technical person could build a really quick app where the back-end is a service. Kind of like, if you remember Parse, by any chance?
David: Yeah, sure, of course, of course, yeah. I remember Parse. When [00:21:00] it landed it was great, and then they actually did some wonderful things in terms of the developer engagement and then they went away as fast as they came. So ...
Greg: Yep, they got bought by Facebook and that was kind of it for whatever reason. But the concept was really cool, where it was a backend service and you could just write a Swift app and not have to worry about the boiler plate stuff. So back to the security ...
David: I'm looking at here, you ... did you click on ...
Greg: Yeah.
David: Yeah.
Greg: Apology, I go back.
David: A moment before, you clicked on Node, or, oh, you clicked on that.
Greg: Oh no, no, no. Let's look at Node. We can click on Node. So Node pops open and we get ... if I go to copy it, you'll see that we're going to ... actually, I'm going to go right to the, let me quickly go in here.
So you can see the request parameters, you can see the responses, all that. I'm going to copy the code quickly. And it says I need the API key. So we'll click this, we'll log in first, because it's not going to work unless we have an API key. [00:22:00] So we'll do that. Okay, so right now, you have an API key.
This API key can be used for any service on ReadMe, if a credit card is attached to it, so if the service costs money, then it takes care of billing, everything that'll, alert you and everything that's there's a charge without you asking.
David: Okay.
Greg: And you can copy and paste this and run it, and it would work. Just make it a little simpler, we'll run the command line version. So go back to this and I can run it. And this time looks very similar to what we just did, but it's actually hitting the server now. It'll take a second because the first time, service hits a little slow, but there we go, we got our math done.
David: This is similar to a cURL command. Just a little bit different.
Greg: Yes. Yep. So I'll see the cURL command. One thing to notice, let's look at the Node thing. It's very similar to an SDK, you'll see that there's no URLs, there's no header params, there's no URL encodings, or nothing like that. The whole point is to really strip APIs down to the most basic level possible. [00:23:00] So we're calling API, we're calling PW, which is what we call the ProgrammableWeb and it uses the registry to figure out where to direct that. There's no URLs, there's no ... so of course it's not good for everyone. There's bigger companies that need more control, they need more of the headers, things, stuff like that. The goal of this is to pair it down as much as possible. In a second I'll show you why that's actually really cool. Other than the fact that it's really simple.
So I'm going to refresh here. And we should see ... actually I'm going to call it. I'm going to grab this. I'm just going to call it on a command line. Okay. So I'm going to have to install the API tool locally as well. We have my API key, we have all the code. For some reason the Vim's not going to hack with me today.
David: I love the fact that you use Vim. I mean, that's pretty hard core, my friend.
Greg: I'm doing this just to impress you David.
David: I mean you could use Sublime, or Atom. Any one of the great [00:24:00] code editors out there, but you use Vim. Okay.
Greg: Oh. I think this is not going to work, because for whatever reason I have to, I upgraded X code and nothing's happy with me right now. In theory, it would work.
We bought API, the [Node] package name, and the Gem word, whatever, and a bunch of languages. So we have Ruby and Python and Node and PHP. This is really easy to call, you just call "api <whatever>. Okay, so you see down here we have logs now. So this is the log from the call we just made. You can see I'm passing 5 and 3, the response was 15.
Let's say that for whatever reason, I don't think that's right. I don't think 5 times 3 should be 15. This is where it's actually really cool. I can create an issue and I can say, wrong number. I don't think five times three is equal to 15. I'm clearly wrong about that, but for the sake of argument.
David: Yeah, I get it. You're basically ... this is kind of like [creating] a GitHub issue.
Greg: Yep.
David: But you're filing it.
Greg: But the cool thing about this though is [00:25:00] that if I submit it, the creator of the API will actually be able to see the logs.
David: Generate a report.
Greg: Yep. So, they'll be able to see, "Oh ...
David: They see the context, they see ... I can see down there, where did they call it from.
Greg: Yep. It's written in Node. It's written, obviously the command line thing, it's ... it kind of makes it really easy for debugging and going back and forth and this is all a very contrived example, of course.
To your point earlier, because I created this API, I can see everyone who's using it. Currently it's just me. But I can view all my, everyone's logs, I can block myself, or I can block someone else from using it. If I made this private, I could, would be opt in. I could only add just you David. If I had a private API.
One cool thing that I want to talk about that we haven't talked about yet is versioning. So one of the hardest things about APIs they break all the time. Let's say that you have an API, you fix a bug. That could break someone's API out there. So for us, all versions are immutable. Which [00:26:00] means if I make a change and then launch a new version, whenever the consumer started using an API, they're locked in that version forever. So, let's say I released a version two. But you started using it on version one, you're still locking version one until you upgrade. Which means that, the cool thing about that, it means that in theory, your API will never break. You don't have to worry about parameters being removed or added.
David: But I could selectively eliminate version one, if I want to, right? I mean, you can imagine, like an API provider's point of view, they do often have multiple versions in production at any given point in time. But at some point, they start to fully deactivate those versions, because it's just too expensive to support and maintain 30 different versions in the wild, right. So you can still manage that.
Greg: Yeah there is a way to, I could mark as deprecated, which is a very soft deprecation, which would just give you a warning, that says hey should I upgrade to version 2.
David: How does it give you that warning?
Greg: Sure. So ...
David: Well you don't have to show it, [00:27:00] I'm just ... does it send me an email as a registered user, does it show up in the response to the API call? What happens there?
Greg: So both. You'll get an email that says, "Hey, your version is deprecated. You should upgrade." If you were to try to upgrade, it would be able to know what parameters you have been using, what end points you were using. And it can kind of ... it can't definitely know that nothing's going to break, but it can kind of be like, Yeah, it seems like things are going to be okay. You can see stats of who is using what endpoints and stuff like that, as the creator.
So that's a soft deprecation. You also get, every time a call's made, you'll get a ... it'll log it on the command line. It'll say, hey, you're on version one, but version two it's deprecated, you should upgrade to version two.
David: This is ... you're using a CLI, not a ...
Greg: Both. It's also if you're calling programmatically, it'll log it to the logs.
David: It will log it to the logs, but it doesn't come back in the response to ... whenever there's an API call.
Greg: No user will see it. It's a ... it's only for the logs. In your email.
David: Check your logs. That's [00:28:00] pretty important.
Greg: Yes.
David: Yeah.
Greg: And you'll get an email as well, so it's not a huge deal. And then you can do a hard deprecation and you could say, okay, everyone on version 1 is ... we're deleting version 1, everybody has to go to version 2.
David: Okay.
Greg: And that would be a breaking change, but in theory, we would give you enough tools to know ... you'll be able to say, "Oh, okay." And only 20 people are using this one endpoint that we changed or deleted. And we know that we've been warning them for a month. They should know it's coming. Kind of giving you the ... we're giving people the ... we're still letting people deprecate stuff, or delete stuff, but we're making it so that hopefully when you do it, you can see statistics and see, "Okay. I can safely delete this, because only four people are using it and they're not really using it. They use it once in a while and it sucks, but I think we can delete it for these four people. And they'll get mad, but you'll each have that knowledge."
David: You know, one thing I'm looking, one thing as I listened to you talk about it and look at it, I think that ... you said this sort of targets smaller businesses, [00:29:00] start-ups, that kind of thing. That they're just getting going. But I can imagine larger enterprises using this to prototype the design of an API and get something up and running pretty quickly that developers can play with, particularly in the reporting issue where you can report issues, because it is exactly that one thing that's often missing in the API lifecycle, which is the ability to get the designers and the product manager and the developers collaborating over the design of the API to make sure that by the time you're ready to put it in production, it totally rocks. Right.
Greg: Yeah. We're both familiar with mocking services.
David: Yeah.
Greg: We could make our own little mocking service ...
Whoops, wrong file.
... by going in and ... rather than doing, touching the database, we could just do api.success and [00:30:00] just pass out data that we hard coded and make a mocking service ourselves.
David: Right.
Greg: So we have several options there.
David: Are there any other really awesome features that you're super proud of that you want to give us a show before we sign-off here.
Greg: Yeah. There's actually ... Yep, there's one more thing that I think is really worth showing. And it's ... so one of the, I don't want to say bad things, clearly empty marketing, but one of the things that might elicit pushback on this is that we don't give you a lot of options. When you enter data in, it has to be flat. There's no nested JSON blob you have to pass. It has to be a flat data structure, when you get data back, it has to be in certain formats. There's a reason for that. It's not because we're trying to restrict people, it's because, like I said before, I don't think that to use an API, you should have to know Python, or Rails or whatever.
So I want to show you how it works with Slack. So I've already added to Slack. If you haven't added to Slack already, you would just click this button, and go through an Oauth flow. But I can copy and paste this little snippet [00:31:00] and I can go into Slack and I can just run it. And it's running it and we get 15 back. And the point is that, I think that APIs, we don't have this yet, but imagine it could be an Alexa skill. It could be a text message that you send and get the response back.
There's a cool company called Clearbit, if you're familiar with it ...
David: Sure.
Greg: ... they're an API company. You can pass an email address, you get back a name. Why should you need to do that via Python or Rails? Why can't there be ... and then you have all these things. Why can't there be a Slack integration? Why can't there be a Salesforce integration? Stuff like that.
Rather than forcing people ... Stripe is on it as well. Stripe has an API, but they've also built a bunch of other ways to consume their API. They have Javascript widgets that take care of all the magic, like do the automagic for you, stuff like that.
David: Yeah.
Greg: So Google sheets. We have Google Sheets integration, I'm not going to share that, because it's a little more clunky, or a little more tough to get going and everything. But it's really cool to scoop up a highlight list of numbers, [00:32:00] hit multiply and then on the third column have all the multiplication stuff. And again, contrived example, you already made the API for that, but ...
David: Of course, all the Google Sheets can probably do that on its own, but I get the point that you're trying to make.
Greg: Math is a very contrived example, but imagine if you had a database.
David: Yeah, if you had a column of email addresses, you could go out ... yeah.
Greg: Yep. Currency conversions, things like that.
David: Sure.
Greg: That's the end of my demo. That's pretty much it. We're launching now, and we're pretty excited just to see how people use it. There's lots of use cases, internal microservices, external public APIs. Yeah, we're excited to see how people use it.
David: Okay. I'm going to turn the screen share off so we can go back to our video mode here.
Greg: Sounds great. Make me presenter.
David: We can see each other.
Greg: Perfect.
David: Last few questions here. So you're just now announcing it. What's the business model here? What does it take for somebody to ... I know you mentioned that if the [00:33:00] API is public, you don't have to pay for it. I'm curious about the rationale behind that decision. And then, if I do, if I make it private, maybe tell us a little bit about that, because it looks like your endpoint is sort of a public end point, you're just ... so I'm wondering how I get it behind my firewall, if that's what I want to do.
Greg: Sure. So the business model is ... originally we were going to charge people to create APIs. But that seemed like it was punishing the wrong people. Of course, most business models are sort of punishing popularity. But ...
David: Punishing somebody.
Greg: Yeah. So the way that it works is that ... it's kind of like GitHub, basically. Where you wouldn't charge someone at GitHub if they're building an open source project. Our APIs aren't open source, but their open access could be a good way to put it. Where it's free to build and if you're consuming, that's when you start to pay. It's free to consume until you [00:34:00] hit the rate limit threshold for different APIs, then you have to buy more calls.
David: What's the rate limit? Is there ... do you know what they are off hand?
Greg: Sure. We'll see. We're going to ... we kept them low, we're not going to keep raising them. But right now it's 100,000 API calls is free for consuming. On public APIs.
David: Per day?
Greg: Per API key. Oh. Per month, sorry. Per month.
David: Per month. Okay.
Greg: So you can make 100,000 API calls for free and then if it's more than that, it starts at 10 bucks a month.
David: Okay.
Greg: And honestly, that's not the business model in the sense that we're not trying to make money off that, that's just more of a limit so that people don't just write infinite loops that really just crush servers, or whatever.
David: Right.
Greg: So the actual business model is two parts.
One is something that we'll offer now. And one is something that's going to come in the next few weeks.
Right now what we do is, if you want it to be an internal, private API, meaning that either you work at a company and it's an internal microservice, or [00:35:00] if you work at a company, you only wanted three or four people to be able to access it. Maybe you build an API for partners, like partner API. Then we would charge per API key that accesses it, it's 10 bucks a month.
David: With no rate limits?
Greg: There are rate limits, but they're much higher. It's a million, I believe. A million hits. And then if you want more, yeah, if you want more, it's 10 bucks.
David: For 10 dollars, a million hits per month, per API?
Greg: Yep. No.
David: Per API key.
Greg: Per API key. Yeah. Exactly. And we'll see how that goes, I'm not really sure the order of magnitude of what people are going to do, so we might raise those. We'll see.
David: How do I get that behind my firewall? Or can I?
Greg: Yep. So right now, the answer is no. But that is pending interest, which I'm sure there will be interest. Because I think as far as business models goes, I think this is not going to make us much money early on. Because we want to encourage free APIs.
Down the line, I would love ... I think the magic is not that we're hosting it. No one cares that part, because [00:36:00] they want to host it on their own infrastructure. I think the real strength is that, you know, the user experience. Like that's ... we're not a technology company, we're a user experience company, is the way I look at it.
So we'll have an on-premise version eventually. Depending on how interested people are or whatever. And I think that would be great for people who want to use it just internally as their microservice, kind of a light-weight microservice, kind of management provider. Obviously as you know, Google has released one, a bunch of companies have released really powerful microservice stuff. This one kind of targets the people who are ... they want to use microservices, they want the feature I just showed you, but they don't need like a mesh network that is scaling for billions of users.
David: Sure.
Greg: They want something that's ... more usability than ...
David: And if I need to connect that to my own data sources? That's all done in that first chunk of code that you were showing us? Where you ...
Greg: Yeah, you would write just like ... it's just like if you were connected to the databases in Heroku, you would just pull in Mongo and you would write [00:37:00] ... or Postgres or whatever. Same exact way. We don't ...
David: Or make API calls to other servers. Yeah.
Greg: Yeah. A lot of people using us now just use it as almost a proxy. Not great, but it actually is nice, because they could do whatever they want on their own servers behind their firewall, and we'd basically take of the UI, UX, simplifying it. So they're likely using us as proxy now. As well.
David: Okay. Well Greg Koberger, founder of ReadMe.io announcing ReadMe, is it ReadMe Build, is that what it's called?
Greg: Yep. We just call it ReadMe Build.
David: ReadMe Build. Announcing ReadMe Build. So congratulations on the launch and we wish you luck with the product and we look forward to catching up with you the next time you have some other great announcement.
Greg: Sounds great. Thank you so much for having me.
