Table of Contents
Overview
OSRF methods can be called via HTTP as browser requests, returning JSON objects or XML documents. JSON is the default, though XML can also be specified. To use XML as the parameter input type, an XML document must be POSTed; this will not be covered at this time (this does not apply to method calls that take no parameters).
Syntax for Calling OSRF Via Web Browser:
http://www.<base url>/osrf-gateway-v1?
format=<return format>&
input_format=<input format>&
service=<OSRF application name>&
method=<Name of Registered OSRF Method>&
param=<param1 value>&…¶m=<param n value> for n parameters.
format and input_format are optional; if neither is present then the request will return a JSON object. To request an XML document, "format=XML" and "input_format=JSON" should be used (the input_format parameter is not strictly necessary, but is a good idea).
The value for the service parameter is the name of the OpenSRF application; for example, open-ils.auth, open-ils.search, or open-ils.actor. The value for the method parameter, likewise, is the registered OSRF method to be called.
Order matters for the param parameters; they must be ordered as they are in the method declaration for the osrf application.
Examples:
Example 0: Check Evergreen version
Returns this:
{"payload":["3-2-0"],"status":200}
Example 1: Retrieve a List of Circ Modifiers with Input Format and Return Format as JSON:
Both of these examples return the same values; the return and input types do not need to be explicitly stated when requesting JSON objects.
Service/Method Registration:
From /openils/lib/perl5/OpenILS/Applications/circ.pm:
__PACKAGE__->register_method( method => 'fetch_circ_mods', api_name => 'open-ils.circ.circ_modifier.retrieve.all'); sub fetch_circ_mods { my $conf = OpenSRF::Utils::SettingsClient->new; return $conf->config_value( 'apps', 'open-ils.circ', 'app_settings', 'circ_modifiers', 'mod' ); }
URL Syntax: Implicit Default (JSON) for Input/Return Type
So, the service name is open-ils.circ and the method name is open-ils.circ.circ_modifier.retrieve.all. This method takes no parameters, so there are no params in the url:
{"payload":[["art","atlas","audiobook","av","new-av","bestseller","bestsellernh","book","cd","dvd","dvd-long","e-book","equipment","filmstrip","kit","magazine","map","microform","music","record","software","softwrlong","equip-long","talking book","toy","video","video-long"]],"status":200}
URL Syntax: Explicit Declarations of Input/Return Type as JSON
Declare return format but not input format: https://demo.evergreencatalog.com/osrf-gateway-v1?format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
Declare input format but not return format: https://demo.evergreencatalog.com/osrf-gateway-v1?input_format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
Declare both return and input formats: https://demo.evergreencatalog.com/osrf-gateway-v1?format=json&input_format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
All of these return the same response:
{"payload":[["art","atlas","audiobook","av","new-av","bestseller","bestsellernh","book","cd","dvd","dvd-long","e-book","equipment","filmstrip","kit","magazine","map","microform","music","record","software","softwrlong","equip-long","talking book","toy","video","video-long"]],"status":200}
Return Format as XML
<response> <payload> <array> <string>art</string> <string>atlas</string> <string>audiobook</string> <string>av</string> <string>new-av</string> <string>bestseller</string> <string>bestsellernh</string> <string>book</string> <string>cd</string> <string>dvd</string> <string>dvd-long</string> <string>e-book</string> <string>equipment</string> <string>filmstrip</string> <string>kit</string> <string>magazine</string> <string>map</string> <string>microform</string> <string>music</string> <string>record</string> <string>software</string> <string>softwrlong</string> <string>equip-long</string> <string>talking book</string> <string>toy</string> <string>video</string> <string>video-long</string> </array> </payload> <status>200</status> </response>
Example 2: Retrieve a Copy by Copy ID
Service/Method Registration:
From /openils/lib/perl5/OpenILS/Applications/Biblio.pm:
__PACKAGE__->register_method( method => "biblio_search_tcn", api_name => "open-ils.search.biblio.tcn", argc => 3, note => "Retrieve a record by TCN", ); sub biblio_search_tcn { my( $self, $client, $tcn, $include_deleted ) = @_; $tcn =~ s/.*?(\w+)\s*$/$1/o; my $e = new_editor(); my $search = {tcn_value => $tcn}; return { count => scalar(@$recs), ids => $recs }; }
URL Syntax: Return Format as JSON
So, the service name is open-ils.search and the method name is open-ils.search.asset.copy.fleshed.retrieve. The $self and $client parameters aren't included in the URL (these are handled by OpenSRF) and, in this case, $include_deleted is optional, so the only parameter that must be included is the copy id:
{"payload":[{"__c":"acp","__p":[null,null,"CONC4000036",36,null,{"__c":"aou","__p":[null,4,5,4,5,4,"Example Branch 1",3,2,"BR1","br1@example.com","(555) 555-0271","t",1]},null,"t",null,"2014-04-18T13:30:03-0400","2014-04-18T13:30:03-0400",1,"f",null,"f","0.00",null,null,"2014-04-18T13:30:03-0400",1,1,"t",1,1,{"__c":"acpl","__p":["t","t","t",1,"Stacks","t",1,null,null,"","","f","f"]},"t",null,"f",{"__c":"ccs","__p":["t",0,"Available","t","t","f"]},"2014-04-18T13:30:03-0400","t",null,null,null,null,null,null,null,null,null,null,[]]}],"status":200}
URL Syntax: Return Format as XML
<response xmlns="http://opensrf.org/-/namespaces/gateway/v1"> <payload> <array class_hint="acp"> <null/> <null/> <null/> <array></array> <null/> <null/> <string>31029005002342</string> <number>1</number> <null/> <array class_hint="aou"> <null/> <null/> <null/> <null/> <null/> <null/> <number>229</number> <null/> <null/> <string>Wadley Public Library</string> <number>3</number> <number>226</number> <string>JCL-WADLEY</string> <null/> <null/> <string>t</string> </array> <string>VIDEO</string> <string>t</string> <number>1</number> <string>2008-01-30T16:55:44-0500</string> <number>1</number> <string>f</string> <string>f</string> <number>0</number> <null/> <null/> <string>2008-01-30T16:55:44-0500</string> <number>1</number> <number>2</number> <string>t</string> <number>1</number> <number>2</number> <array class_hint="acpl"> <null/> <null/> <null/> <string>t</string> <string>t</string> <number>1</number> <string>Stacks</string> <string>t</string> <number>1</number> </array> <string>t</string> <number>12.980000</number> <string>f</string> <array class_hint="ccs"> <null/> <null/> <null/> <string>t</string> <number>0</number> <string>Available</string> </array> </array> </payload> <status>200</status> </response>
Since this example takes a parameter, "input_format=json" must be used in conjunction with "format=xml." Otherwise, the method has an internal error (note, though, that the returned status is'200'). https://demo.evergreencatalog.com/osrf-gateway-v1?format=xml&service=open-ils.search&method=open-ils.search.asset.copy.fleshed.retrieve¶m=1 returns:
<response xmlns="http://opensrf.org/-/namespaces/gateway/v1"> <payload> <object> <element key="desc"> <string>Someone attempted to retrieve a copy object from the system and the object was not found.</string> </element> <element key="id"> <null/> </element> <element key="ilsevent"> <number>1502</number> </element> <element key="pid"> <number>3995</number> </element> <element key="servertime"> <string>Mon Mar 24 17:27:55 2008</string> </element> <element key="stacktrace"> <string>/openils/lib/perl5/OpenILS/Application/AppUtils.pm:992 /openils/lib/perl5/OpenILS/Application/Search/Biblio.pm:257/openils/lib/perl5/OpenILS/Application/Search/Biblio.pm:257</string> </element> <element key="textcode"> <string>ASSET_COPY_NOT_FOUND</string> </element> </object> </payload> <status>200</status> </response>
Example 3: Authentication
Login with the demo admin user:
Returns this:
{ "payload":[{ "ilsevent":0, "textcode":"SUCCESS", "desc":"Success", "pid":19776, "stacktrace":"oils_auth.c:636", "payload":{ "authtoken":"5f0f7eebe600ed267be4085b660fe7be", "authtime":7200 } }], "status":200 }
Return Status
OSRF methods will return a status as part of the JSON object or XML document.
Status | Payload Contents | Recommendation |
---|---|---|
200 | The OpenSRF request is returned successfully; the payload contains the returned object (however, check the payload, as there may have been an error at the method level, as in the above example). | |
404 | [],"debug": "osrfMethodException : Not enough params for method <method name> / service <service name>" | Check the method's parameters; if the correct parameters are being passed, verify that param is spelled correctly in the URL. |
404 | [],"debug": "osrfMethodException : Method [<method name>] not found for <service name>" | Check the method name against the method's osrf registration, and verify that the service parameter points to the correct service. |
404 | [],"debug": "osrfMethodException : An unknown server error occurred" | Verify that input_type is not "xml". |
404 (Apache Error) | "The requested URL /osrf-gateway-v1 was not found on this server." | Check that method and service are spelled correctly |