Introducing ReadMe Build

We launched ReadMe a few years ago with the goal of making APIs simpler to use through documentation. It’s going really well, but we started to realize that documentation is only as good as the API. So, now we want to help people build great APIs as well.

We believe APIs should be simple. Like, really simple. In theory, you pass an API some data, something happens, and you get data back. That’s it! They should be like Legos you piece together to build something real. Yet we overcomplicate them with weird URL encodings, content types, auth methods, SDKs and more. (Don’t believe me? Check out the size of the Open API Spec, which enumerates some of the complexity of current APIs.)

Calling an API should be as dead simple as calling a function natively.

That’s why we made ReadMe Build. We wanted to take what we love about APIs, and cut out the rest. For example, check out an example of how to call an API created using ReadMe Build:

const api = require('api').config('demo_2jk34l2k1');
    
api('text').run('send', {
  to: '+1514-651-4227',
  message: 'Your package has been delivered!'
}, (err, response) => {
  console.log(response);
});

Note how there’s no URLs, nothing needs to be URL encoded or stringified, no content type is passed in. And while we support a number of languages, we don’t believe APIs need to be consumed via code: APIs can be called from the command line, Slack, Google Sheets, and many more to come.

But it’s more than just this! When you use an API on Build, it comes with thorough, dynamic documentation. Let’s say an API stops working for some reason. Going to the docs won’t serve up the same static content as when you first signed up for it. The docs will know if the API is down in general, or maybe if you hit your rate limit. You can see logs for every request you make. If something feels off, you can create an issue and attach actual logs to it, and the API creator can see exactly what data you sent in and got back.

Building APIs

Consuming APIs isn’t the only easy thing with Build… making APIs are just as simple. Imagine if you could just write the basic code specific to your API, and you got things like logs, authentication, rate limiting, monitoring, SDKs code samples and hosting out of the box? And on top of that, it’s free to make and publish public APIs!

It’s as simple as installing the api tool, and running api init:

$ api init
... edit code ...
$ api deploy

Once you type api deploy, your API is out there for anyone to use! You can build an API and have it out there for the world to use in literally minutes.

And the best part is how closely tied to your docs the API is. When writing code, you document your API in the comments above it, like this:

/*
 * This API will multiply two numbers together
 *
 * @param {number} x=0 First number
 * @param {number} y=0 Second number
 * @throws {ValidationError} Must provide all required fields
 * @returns {number} The result
 */
module.exports = (data, api) => {
  if (!data.x || !data.y) return api.error('ValidationError');
  api.success(data.x * data.y);
};

Consuming APIs

Consuming APIs is just as easy! We bought the api package/gem/etc in most major package managers, so it's easy!

const api = require('api').config('demo_j2k3jklz');

api('text').run('send', {
  to: '+1514-651-4227',
  message: 'Your package has been delivered!'
}, (err, response) => {
  console.log(response);
});

Final thoughts

Your API only has one goal: to be used. The simpler your API, the more people who will use it. That’s the goal of Build – to make it as simple as possible to build, deploy and share APIs.

Convinced? You can start using it right away! Either sign up on the site, or type the following into the command line:

$ npm install api -g
$ api init

Let us know what you think!