Everyone,
For a long time, I've been wanting to find a better way to interface
with the HTTP protocol that HTTPAPI provides... currently, most people
are using these routines:
http_url_get(), http_url_get_raw(), http_url_get_xml()
http_url_post(), http_url_post_raw(), http_url_post_xml()
While these provide access to the GET and POST methods, I see several
big problems with them:
1) There are too many parameters for things like timeout, user agent,
soap action, etc. To me, this makes the code awkward.
2) There is no really easy way to simply get the result as a string.
My original design in 2001 was that a callback approach would be very
versatile -- and it is -- because you can code any logic you want for
where to store the data when it comes in. But in perhaps 95% of the
cases, you want it in a string or in a stream file. So having to code
the logic to write to a string every time seems cumbersome.
3) Only supporting GET/POST is limiting, especially with REST.
4) Automatically calling an XML parser is kinda neat, but not really
required anymore, since RPG now has one built-in. Plus, XML is fading
in popularity in favor of JSON. People get confused when they see XML
routines but no routines for other formats like JSON, MIME or
URL-encoded forms. They think HTTPAPI is limited, when in fact, it
was designed to be as versatile as possible.
So I was thinking of a new interface that, really, is one core routine:
http_req() = make an HTTP request.
Parameters would be:
method = HTTP method to use (GET, POST, PUT, DELETE, etc)
URL = the URL, of course
Where to put the response... two parmeters for that:
RecvStmf = If you want the response put into a stream file (IFS) then
you pass this, otherwise use *OMIT
RecvString = If you want the response put into a string, you pass
this, Otherwise *OMIT
Where to get request body from.. only used for POST/PUT methods,
otherwise you can leave them off
SendStmf = stream file to send request body from, or *omit to send
from a string
SendString = string to send request body from, or *omit to send from a
stmf
For body the body and the response, you can either use one or the
other, not both. This might lead to confusion? But, it surely would
be simpler than what we have now. It'd look like this:
req = '<something>some request to send</something>';
http_setOption('content-type': 'text/xml');
rc = http_req('POST': 'http://whatever': *omit: resp: *omit: req);
// resp now contains the response document (XML, JSON, HTML, whatever
it is.)
The http_setOption() routine allows you to set any of the options that
might've been extra parameters before.
We could also have some "simpler" wrappers around this routine for
working with strings and/or stream files. I'm thinking that the
wrappers would (a) send an exception message for errors, so rc isn't
needed, (b) only accept one parameter for data to send, and one to
receive. There'd be two wrappers, one for using strings, one for
using files.
Resp = http_string('GET': 'http://whatever');
Resp = http_string('POST': 'https://foo.bar': dataToSend);
http_stmf('GET': 'http://whatever': '/home/scott/myresponse.xml');
http_stmf('PUT': 'http://foo': '/tmp/response.dat': '/tmp/request.dat');
All the old routines would be retained, of course, so existing
programs would work without problems. Instead of using the automatic
XML parsing, you'd just receive your data to a string, and then parse
the string afterwards. (using RPG's built-ins, or HTTPAPIs
http_parse_xml_String routine, or SQL's XML stuff) Likewise for JSON
you could use YAJL, SQL, or your favorite 3rd party tool. It's a
string, right? You can feed it into anything.
Let me know your thoughts!
_______________________________________________
Ftpapi mailing list
Ftpapi@xxxxxxxxxxxxxxxxxxxxxx
http://scottklement.com/mailman/listinfo/ftpapi