Innovation API Help

This document details the use of the iBridge^SM Network API to programmatically manage innovations, products, and related materials for your institution. The API allows you to create, read, update, and delete these records in the iBridge Network database without using a browser to interact with the site.

The topics covered in this help are:

The Protocol
Supported Actions
Request and Response Formats
Getting Help

The Protocol

The iBridge^SM Network API is an HTTP based protocol, so you can interact with it using normal Web requests. Sending requests to the API is identical to filling out a form on a Web page and submitting it to the server. All requests should be sent as HTTP POSTs.

Any programming language in popular use today should have a library available for building and sending these requests. You can even deliver them using command-line utilities like curl or wget.

Sending Requests

I’ll use curl to show a sample request to the iBridge Network API. In this request I will ask the Web site to show me the current database record for a fictional innovation in a fictional institution:

$ curl -F api_token=873e42ea226fb
       -F records=@-
       http://www.ibridgenetwork.org/api/read
       <<< '<innovation file_number="123" />'

To break that down, the -F switches are setting the form parameters the API expects. The first one is an API Token required by all API requests to the Web site. To locate that token for your institution, log into the iBridge Network application as an administrator for the institution and visit the “Edit INSTITUTION_NAME Profile” form in the administration actions. This page will display the API Token that you will need when interacting with the API.

The second parameter allows me to specify a file containing my XML request. All requests that need input expect this records parameter containing valid XML content which will be described in Request and Response Formats. My needs were simple in this case, so I just used STDIN and inlined the XML at the end of the command using my shell’s herestring syntax. If you had the data in a file called “request.xml” instead, you would change the second switch to “-F records=@request.xml”. This sends the records parameter as a file upload allowing the server to handle large requests, which will be important for actions like Sync that need a lot of data.

Finally, take note of the URL used in this request. The protocol, domain, and literal “api” reference will be the same for all requests. Only the last bit changes, to reflect the desired action for this request.

Note that you can add the -i command-line switch to curl calls if you want to see the status code and headers returned by the API.

For comparison, here are similar examples in some popular scripting languages. First we have Ruby:

#!/usr/bin/env ruby -wKU

require "net/http"
require "uri"

response = Net::HTTP.post_form( URI.parse("http://ibridgenetwork.org/api/read"),
                                :api_token => "873e42ea226fb",
                                :records   => DATA.read )
case response
when Net::HTTPSuccess
  puts response.body
else
  puts "Server Error:  #{response['Error-Message']}"
end

__END__
<innovation file_number="123" />

Here's a Perl version:

#!/usr/bin/env perl

use strict;
use warnings;

use LWP::UserAgent;
use HTTP::Request::Common "POST";

my $ua  = LWP::UserAgent->new;
my $req = POST "http://ibridgenetwork.org/api/read",
               [api_token => "873e42ea226fb", records => <DATA>];

my $res = $ua->request($req);
if ($res->is_success()) {
  print $res->content;
} else {
  print "Server error:  ", $res->header("Error-Message"), "\n";
}

__END__
<innovation file_number="123" />

Finally, we have a PHP example. This code requires libcurl:

<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_POST,           TRUE); // inform curl to use POST
curl_setopt($ch, CURLOPT_HEADER,         TRUE); // prefix xml with Status etc.
curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); // return string, not html page

curl_setopt($ch, CURLOPT_URL, "http://www.ibridgenetwork.org/api/read");

// iBridge "records" input can be either file or string, but syntax differs
$curl_record = '<innovation file_number="123" />';
if (isset($curl_record)) {
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                array("api_token"=>"873e42ea226fb", "records"=>$curl_record));
} else {
    curl_setopt($ch, CURLOPT_POSTFIELDS,
                array("api_token"=>"873e42ea226fb", "records"=>"@curl_record.xml"));
}

$curl_response  = curl_exec($ch);
$statusOK       = strpos($curl_response, "Status: 200 OK");
if($statusOK === false) {
    echo "*** Status is not '200 OK' in CURL operation -- exit now\n\n";
    exit;
}

echo "$curl_response\n\n";

curl_close($ch);

?>

Supported Actions

The following is a list of actions supported by the iBridge^SM Network API. Actions detail expected input and possible outputs.

The provided actions target innovations, products, related materials in the iBridge Network database. The term records in this document, refers to these entities.

All action except Dump and List require a valid XML document specifying the details for the action as described in the Request and Response Formats section. XML should be passed in a parameter called records.

You can add an invite_users parameter set to “True” to generate invites for users that don't exist on the iBridge Network. User emails must be valid or an error will be returned. Invited users will be sent an email message when their innovations are published. The email message contains a list of all published innovations they are associated with.