4 Things you should know about Clarify

Originally published on the Clarify.io blog. View archived copy.

1. We use Swagger to document our API.

Swagger? It’s a framework for describing, producing, consuming, and visualizing REST APIs. That’s all well and good if you’re an API producer, but what does that mean if you’re a consumer? It means you can test the API by interacting with the docs! This is way cool, and we think it’s the way all API docs should be.

If you want to know more, check out the spec here: https://github.com/wordnik/swagger-spec/. And if you’re an API producer, you’ll find all the Swagger tools you need right here: https://github.com/wordnik.

If you’re a developer, try it out. Click on the Clarify documentation link, then click on the GET /v1/bundles function. You’ll see all the docs including a formal response schema. And of course you can actually run that function over some sample data we’ve provided by clicking on the Try it out! button. How cool is that?!

You know, the Swagger guys love GitHub, and it turns out…

2. We love GitHub (too)!

We use GitHub to host any open source code that could be useful to developers who use our API. Check it out: https://github.com/op3nvoice. Today you’ll find:

• A PHP library,
• a Python library,
• a community-built Node.js library,
• curl examples, and
• some sample players.

The libraries are language wrappers around the API. The curl examples show you how to interact with the API directly from the Unix command line. The sample audio and video players know how to consume the output of our search function. Start with those, then extend them, or build your own!

3. We think hypermedia is awesome!

Have you ever used an API that didn’t natively support pagination? Or worse did you have to write a bunch of code to make sure the client properly asked for and got the next or previous page? Isn’t it crazy that every API client has to write the same code? It is. And that’s one of the problems that hypermedia solves. The server takes care of pagination! All you do is ask for the next or previous page urls which the data itself give you. It’s magic.

Is that it?

Nope.

You know how web pages contain links to other pages? Ever wonder why your JSON data doesn’t? Hypermedia JSON does! In fact, the pagination example I started with is just one use-case. Imagine you retrieve the proverbial invoice that contains 6 detail records. Isn’t it a little crazy to get the detail record IDs and then have to construct URLs to retrieve them? Why should that be your job? Why shouldn’t the server just include those links in the invoice? With hypermedia JSON, that’s exactly what you get. No more URL construction. Ever!

Next, what if I already know that when I retrieve the invoice I’m going to have to turn around and request each of the detail records, wouldn’t it make sense to embed all that data in the invoice? It would. But how would we do that? Should we provide two different API calls? Should we have to pass another argument? And what if there’s more than one thing we want to embed, or the embedded data contains other potentially embedded data. It gets confusing fast.

Luckily, hypermedia solves that for us and defines a way to ask that nested data be included by value instead of by reference. This puts the time/space tradeoff decision in the hands of the developer, where it belongs!

There are a few competing hypermedia specifications out there. We’re using HAL because we think it’s the easiest for non-hypermedia developers to deal with. We’d love to throw everyone into the hypermedia deep end, but we think there are some challenging concepts, so we’re pretty happy that HAL makes it easy to ignore all those weird links. This means you can start off using our API just like any “normal” REST API, but eventually you might want to dive deeper and accomplish things more quickly and easily with the more advanced workflows that hypermedia offers.

And finally, you should know that…

4. The engines behind the API are getting smarter every day!

Behind our API is technology related to Natural Language Processing (NLP), Automatic Speech Recognition (ASR), signal processing, and a variety of PhD-level concepts and functionality. At the end of the day, our is to make the API simple and consistent without requiring you to be an expert on any of the technologies. That means as the underlying technology becomes faster, better, and more accurate, your applications get better without any of the implementation details.

If we do something big, we’ll let you know, but most of the time we’ll just quietly roll out improvements. Relax, we’ll do the heavy lifting!