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

[[https://demo.evergreencatalog.com/osrf-gateway-v1?service=open-ils.circ&method=opensrf.open-ils.system.ils_version]]

Returns this:
<code>
{"payload":["3-2-0"],"status":200}
</code>

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

<code perl>
__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' );
}
</code>

===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 //param//s in the url:

https://demo.evergreencatalog.com/osrf-gateway-v1?service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all
returns: <code> {"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} </code>
===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: 
<code> {"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} 
</code>

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

<code 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>
</code>

=====Example 2: Retrieve a Copy by Copy ID=====

===Service/Method Registration:===
From /openils/lib/perl5/OpenILS/Applications/Biblio.pm:

<code perl>
__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 };
}
</code>

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

<code json>
{"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}
</code>

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

<code 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>
</code>

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:
<code xml>
<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>
</code>

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

<code>
{
"payload":[{
    "ilsevent":0,
    "textcode":"SUCCESS",
    "desc":"Success",
    "pid":19776,
    "stacktrace":"oils_auth.c:636",
    "payload":{
        "authtoken":"5f0f7eebe600ed267be4085b660fe7be",
        "authtime":7200
    }
}],
"status":200
}
</code>

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