examples.js | |
---|---|
IntroductionShred is an HTTP client library intended to simplify the use of Node's built-in HTTP library. In particular, we wanted to make it easier to interact with HTTP-based APIs. A Simple ExampleLet's start simple. We're going to use the spire.io API as our example. Let's begin by getting the documentation for the API as HTML. | |
First, we need to instantiate a Shred instance. We can re-use this instance over any number of requests. The main purpose of creating an instance is to make it possible for you to provide default options that will be applied across each request for that instance. Later, we also expect to allow you to manage connections on a per-instance basis. For these examples, however, a simple Shred instance will work fine. | var Shred = require("shred");
var surf = new Shred; |
We're going to check our responses with | var assert = require("assert"); |
So now let's get that documentation: We have to let the spire.io API know that we want the docs as HTML. | surf.get({
url: "http://api.spire.io",
headers: {
accept: "text/html"
},
on: { |
Response events can be specified in terms of response codes. More specific events have precedence. | 200: function(response) {
assert.ok(response.content.body);
console.log("√ Got API description as HTML");
}, |
Here, | response: function(response) {
console.log("We got something besides a 200 response!")
}
}
}); |
We can also chain response handlers and have many handlers for the generic 'response' event. | surf.get({
url: "http://api.spire.io",
headers: {
accept: "text/html"
}
}).on(200, function(response) {
assert.ok(response.content.body);
console.log("√ Got API description as HTML");
}).on(function(response) {
console.log("We got something besides a 200 response!");
}).on(function(response) {
console.log("I'm not so happy about this non 200 response. Launch the missiles!");
}); |
Data ConversionShred provides a very helpful facility for converting content entities to and from Javascript data types. The conversion is based on the content type of the entity. Let's try asking for the API description as | |
First, let's declare a couple of variables we'll be using in later examples. | var resources, schema;
surf.get({
url: "http://api.spire.io",
headers: {
accept: "application/json"
},
on: { |
This time, instead of asking for | 200: function(response) {
assert.ok(response.content.data); |
We can treat this as an ordinary Javascript object: | assert.ok(response.content.data.resources.sessions.url); |
Let's save some of this for later. | resources = response.content.data.resources;
schema = response.content.data.schema["1.0"];
console.log("√ Got API description as JSON");
},
response: function(response) {
console.log("We got something besides a 200 response!")
}
}
}); |
We can do the same trick to | |
This time, we're going to wrap our call to Shred in a function, so that we can use it in a callback. | var createSession = function() {
surf.post({
url: resources.sessions.url,
headers: {
accept: schema.session.mediaType, |
Shred will automatically normalize the header names for you. Here,
| content_type: schema.account.mediaType
}, |
This is the new bit. We just pass a Javascript object and Shred converts it for us. | content: { key: "c9KfjaIirRlg9YKpCck97Q-1321321628" },
on: { |
This time, we want a | 201: function(response) {
assert.ok(response.content.data); |
We'll save the session for future reference | resources.session = response.content.data;
console.log("√ Created a session.");
},
response: function(response) {
console.log("We got something besides a 201 response!")
}
}
});
}; |
We'll call it using | setTimeout(createSession,1000); |
Error Handling | |
Let's see how Shred error handling works. We'll attempt to create channel
using the spire.io message service. However, we'll "forget" to include
an authorization header. This should give us back a | |
Now, we could simply handle this via the | var createChannel = function() {
surf.post({
url: resources.session.resources.channels.url, |
Normally, we'd pass in a authorization header, too. | headers: {
accept: schema.channel.mediaType,
content_type: schema.channel.mediaType
}, |
We'll try to create a channel named "foo". | content: { name: "foo" },
on: { |
The | error: function(response) {
assert.equal(response.status,401);
console.log("√ Handled channel create error.");
},
response: function(response) {
console.log("We got something besides an error response!")
}
}
});
}; |
Again, you'd normally call this function in an event handler. | setTimeout(createChannel,2000); |
You can also handle redirects explicitly using the | |
Other Resources
| |