[ann] xquery-wmata: an EXPath-based library for accessing Washington DC-area subway & bus API

[Joe Wicentowski]

Hi all,

I wanted to share an XQuery library I just released for accessing the
API of WMATA, the Washington (DC) Metropolitan Area Transit Authority.
The library is a pretty simple wrapper around the API methods defined
at http://developer.wmata.com/docs. Thanks to the EXPath HTTP module,
I was able to make HTTP requests to the API endpoints in what I hope
is a cross-implementation-friendly manner. I am using the library
with eXist, but I would welcome anyone with other XQuery
implementations that support the EXPath HTTP module to take my module
for a spin. I did my best to comment up the module using XQDoc too,
so I hope it's understandable. Comments, forks, and pull requests are
welcome.

https://github.com/joewiz/xquery-wmata

Cheers,
Joe

[Florent Georges]

On 2 December 2011 16:59, Joe Wicentowski wrote:

Hi Joe,

First, sorry for the late response. I was on holidays
somewhere in between and had to catch up some work since I came
back :-(

> I wanted to share an XQuery library I just released for
> accessing the API of WMATA, the Washington (DC) Metropolitan

> Area Transit Authority. [...] Thanks to the EXPath HTTP

> module, I was able to make HTTP requests to the API endpoints
> in what I hope is a cross-implementation-friendly manner.

> https://github.com/joewiz/xquery-wmata

Thanks for sharing this!

I don't know WMATA, so I can't comment on the library itself,
but I think the idea is very good: what better languages than
XQuery (or XSLT or XProc) to manipulate the XML to send to and to
consume from Web services?

If you are interested in this, I made a fork on Github, in
order to adapt the project to follow the EXPath Project Manager
conventions, so a package can be built automatically out of it,
as well as building a release file or running tests.

Once this structure has been applied (basically that means
putting source code in src/, XSpec test suites in test/ and
informations about the project itself in xproject/), one can use
the following commands from the shell:

# the steps here under do the following things:
# 1/ go to the project dir
# 2/ build the XAR package
# 3/ build a ZIP file containing the package and other files
# 4/ e.g. this is the content of the generated file VERSION
# 5/ run the test suites (I enclose a screeshot of the report)

> cd /somewhere/wmata

> xproj build
Building project file:/somewhere/wmata/
Generated XAR file dist/wmata-client-0.1.0.xar

> xproj release
Releasing project file:/somewhere/wmata/
Generated ZIP release file dist/wmata-client-0.1.0.zip

> unzip -p dist/wmata-client-0.1.0.zip wmata-client-0.1.0/VERSION
Version: 0.1.0
Revision: 2ee0023

> xproj test
INFO: file:/somewhere/xspec/harnesses/harness-lib.xpl:180:42:
passed: 3 / pending: 0 / failed: 0 / total: 3
<suites>
<processor name="http://expath.org/tmp/exist/xquery">
<suite uri="file:/somewhere/wmata/test/simple.xspec"
report="file:/somewhere/wmata/test/simple-exist.html"/>
</processor>
</suites>

I also added a CXAN descriptor, which is automatically packaged
too, so then the result can be added automatically to CXAN (see
http://cxan.org/).

So just a few words about my changes, that you can find in
https://github.com/fgeorges/xquery-wmata. First, I had to rename
one of the functions wmata:get-bus-stops, because there were two
of them. I renamed it to wmata:get-bus-schedule-by-route (I
think that's simply a bug in the module).

- I created a subdir src/ and moved the library module in there
(and renamed it from .xqm to .xql, to emphasise this is a
library module, not a main module)

- I created a subdir test/ and added a sample XSpec suite

- I created a subdir xproject/ and added informations about the
project itself (in project.xml, used by the project manager,
mainly to build automatically the XAR package, and cxan.xml
to describe the project in CXAN)

- due to a limitation in parsing XQuery library modules, I
moved the module declaration instruction to the first line in
wmata.xql

So the project structure is now the following:

LICENSE.TXT
README.md
src/
wmata.xql
test/
simple.xspec
xproject/
cxan.xml
project.xml

And after "xproj build", "xproj release" and "xproj test", you
have the three following files as well (that you usually ask Git
and SVN to ignore):

dist/
wmata-client-0.1.0.xar
wmata-client-0.1.0.zip
test/
simple-exist.html

Comments welcome!

Thanks again for sharing, regards,

--
Florent Georges
http://fgeorges.org/
http://h2oconsulting.be/