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>/gateway?format=<return format>&input_format=<input format>&service=<OSRF application name>
&method=<Name of Registered OSRF Method>&param=<param1 value>&…&param=<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 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:

http://demo.gapines.org/gateway?service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all returns:

 {"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: http://demo.gapines.org/gateway?format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
Declare input format but not return format: http://demo.gapines.org/gateway?input_format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
Declare both return and input formats: http://demo.gapines.org/gateway?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

http://demo.gapines.org/gateway?format=xml&input_format=json&service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all returns:

<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:

http://demo.gapines.org/gateway?service=open-ils.search&method=open-ils.search.asset.copy.fleshed.retrieve&param=1 returns:

 {"payload":[/*--S acp--*/[null,null,null,[],null,null,"31029005002342",1,null,/*--S aou--*/[null,null,null,null,null,null,229,null,null,"Wadley Public Library",3,226,"JCL-WADLEY",null,null,"t"]/*--E aou--*/,"VIDEO","t",1,"2008-01-30T16:55:44-0500",1,"f","f",0,null,null,"2008-01-30T16:55:44-0500",1,2,"t",1,2,/*--S acpl--*/[null,null,null,"t","t",1,"Stacks","t",1]/*--E acpl--*/,"t",12.980000,"f",/*--S ccs--*/[null,null,null,"t",0,"Available"]/*--E ccs--*/]/*--E acp--*/],"status":200}

URL Syntax: Return Format as XML

http://demo.gapines.org/gateway?format=xml&input_format=json&service=open-ils.search&method=open-ils.search.asset.copy.fleshed.retrieve&param=1 returns:

<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'). http://demo.gapines.org/gateway?format=xml&service=open-ils.search&method=open-ils.search.asset.copy.fleshed.retrieve&param=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>

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 /gateway was not found on this server.” Check that method and service are spelled correctly
osrfhttp/opensrf_gateway.txt · Last modified: 2013/11/04 14:54 by rjs7
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Debian Driven by DokuWiki

© 2008-2013 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a member of Software Freedom Conservancy.