User Tools

Site Tools


osrfhttp:opensrf_gateway

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>&…&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 0: Check Evergreen version

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:

https://demo.evergreencatalog.com/osrf-gateway-v1?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: 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

https://demo.evergreencatalog.com/osrf-gateway-v1?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:

https://demo.evergreencatalog.com/osrf-gateway-v1?service=open-ils.search&method=open-ils.search.asset.copy.fleshed.retrieve&param=1 returns:

{"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

https://demo.evergreencatalog.com/osrf-gateway-v1?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'). https://demo.evergreencatalog.com/osrf-gateway-v1?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>

Example 3: Authentication

Login with the demo admin user:

https://demo.evergreencatalog.com/osrf-gateway-v1?service=open-ils.auth&method=open-ils.auth.login&param={"username":"admin","password":"demo123"}

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
osrfhttp/opensrf_gateway.txt · Last modified: 2022/02/10 13:34 by 127.0.0.1

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki

© 2008-2022 GPLS and others. Evergreen is open source software, freely licensed under GNU GPLv2 or later.
The Evergreen Project is a U.S. 501(c)3 non-profit organization.