Show me the code!
Let’s take two examples, starting with the browser.
Now consider a connection from nodejs to another API.
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:
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?
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).
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:
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.
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.
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?
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?
Give swagger-js a shot (it’s FOSS, as you would hope):
And you can read more about the spec here: