For Developers

Reverb Developer Blog

The Fastest Way to Connect to an API with JavaScript

by Tony Tam  |  Posted July 18, 2013

swagger-round

Let’s cut to the chase. JavaScript is everywhere. APIs are exploding. And swagger-js is the fastest way to connect from JavaScript to your API, period.

Show me the code!

Let’s take two examples, starting with the browser.

js-1a

Done!

Now consider a connection from nodejs to another API.

js-2

That was easy.

Let’s peel back the onion a bit. Initializing the Swagger client does a couple things. First, it calls the API and reads the Resource Listing (the list of all APIs on the server). Next, it reads each API Declaration and “builds itself”. Let’s pause.

To understand the relationship between the Resource Listing and the API Declaration in Swagger, you can read the wiki. Or to put it simply, the Resource Listing is like a site map for the APIs on the system. The API Declaration is the description of each API itself. Maybe you don’t want to know about all APIs on the system? You can point swagger-js directly at one of the API Declarations when initializing it:

js-3

The scope of the client will be much less (just this API) but that may be all you need. That’s up to the developer.

Next, what does “build itself” mean? Specifically, the JSON structure of the API (as described in the Swagger format) is read. The HTTP method, parameters, response types, content types, etc., are all described in the JSON which tells swagger-js exactly what it needs to in order to make calls. Don’t believe it? Try a different API! How about the US Government’s Federal Agency Directory?

js-4a

Note this time we specified a success callback (because async JavaScript is the right thing to do). Of course just logging into the console isn’t very interesting, but this shows how the library works.

Now let’s pretend that we don’t know what this API even does. What are the operations I can call? What are the parameters? When using the node repl, it’s easy to see (same goes for the developer console in chrome).

js-5

This tells us something important! There’s an identifier flag required to make this call. So we can call it, passing a (valid) identifier flag:

js-6

This is super powerful. Because not only do you know what APIs you can call, you can ask what the parameters are. Calling the API is also easy, and customizing our requests is a breeze.

Another example. Let’s say that your resource isn’t wide open–it requires some fancy authorization strategy. We’ll cover oAuth in a follow-up post but for now, let’s assume you have to pass “some” header in every request. Luckily, this is built into swagger-js.

js-7

How about sending data? Surly there is more to the programmable web than just GET operations, right? Let’s keep in mind that we never said to send a GET–the swagger-js client “knew” to call GET because of the Swagger JSON specification. But here’s how you’d pass data to a server with the same convenience.

js-8

That was easy! Here, we passed the body as a string (swagger-js doesn’t make assumptions about the content being objects). It does, however, default to expect the content-type is application/json How about XML? Remember XML?

js-9

So this is all neat and fancy. But one would say “this only let’s me connect to a Swagger-enabled API”. This is indeed correct. Swagger JSON is a technique to describe the API, and with it, you can have a client for “free”. But what if your API isn’t Swagger enabled?

Remember that you can document virtually any API with Swagger, even if it’s not your own. So as quickly as you can hand-code a JavaScript client, you can build a Swagger JSON specification, which of course doesn’t need to live on the remote server. Like the folks at ApiHub have shown, you can document an API regardless of where it’s hosted.

Give swagger-js a shot (it’s FOSS, as you would hope):

https://github.com/wordnik/swagger-js

And you can read more about the spec here:

https://github.com/wordnik/swagger-core/wiki

Filed under: swagger | Permalink | 3 Comments

{ 3 trackbacks }

Reverberations: Rejection, Die Hard, swagger-js
07.19.13 at 7:28 am
Swagger Offers Lightning Quick Connection To Your API
07.23.13 at 1:27 pm
10 Tech Stories To Read This Week – July 30 Edition | iRomin
07.29.13 at 3:36 pm

{ 0 comments… add one now }

Leave a Comment

You can use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>