User Tools

Site Tools


osrfhttp:opensrf_gateway

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
osrfhttp:opensrf_gateway [2013/11/04 14:54]
rjs7 [Syntax for Calling OSRF Via Web Browser:]
osrfhttp:opensrf_gateway [2022/02/10 13:34] (current)
Line 3: Line 3:
  
 ======Syntax for Calling OSRF Via Web Browser:====== ======Syntax for Calling OSRF Via Web Browser:======
-''http://www.<base url>/gateway?format=<return format>&input_format=<input format>&service=<OSRF application name>\\ +''http://www.<base url>/osrf-gateway-v1?\\ 
-&method=<Name of Registered OSRF Method>&param=<param1 value>&...&param=<param //n// value> for //n// parameters.''+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). //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).
Line 13: Line 17:
  
 ======Examples:====== ======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:===== =====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. Both of these examples return the same values; the return and input types do not need to be explicitly stated when requesting JSON objects.
Line 30: Line 44:
 } }
 </code> </code>
 +
 ===URL Syntax: Implicit Default (JSON) for Input/Return Type=== ===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: 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:
  
-http://demo.gapines.org/gateway?service=open-ils.circ&method=open-ils.circ.circ_modifier.retrieve.all+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> 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=== ===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 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: http://demo.gapines.org/gateway?input_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: http://demo.gapines.org/gateway?format=json&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:  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> {"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> </code>
 +
 ==Return Format as XML== ==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+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: returns:
  
Line 110: Line 126:
 } }
 </code> </code>
 +
 ===URL Syntax: Return Format as JSON=== ===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: 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 +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":[/*--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}+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> </code>
  
 ===URL Syntax: Return Format as XML=== ===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+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: returns:
  
Line 197: Line 217:
  
 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'). 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:+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> <code xml>
 <response xmlns="http://opensrf.org/-/namespaces/gateway/v1"> <response xmlns="http://opensrf.org/-/namespaces/gateway/v1">
Line 228: Line 248:
 </response> </response>
 </code> </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====== ======Return Status======
 OSRF methods will return a status as part of the JSON object or XML document. OSRF methods will return a status as part of the JSON object or XML document.
-STatus      ^ Payload Contents       ^ Recommendation          ^+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).    || | 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 : 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 : 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    | [],"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 |+| 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.1383594887.txt.gz · Last modified: 2022/02/10 13:34 (external edit)

© 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.