[racket] wffi (a "literate" web service "FFI" using a markdown file with parameterized HTTP messages)

From: Greg Hendershott (greghendershott at gmail.com)
Date: Tue Oct 9 18:12:39 EDT 2012

P.S. With my "wffi" markdown thing, and also today experimenting with
the Google API discovery format, I've been circling around a basic
question. I'm curious what other people think.

With both wffi and G-API, it's (fairly) easy enough to have some
Racket code cough up a collection of lambdas wrappers corresponding to
to web service functions.

Great. But: What to do with these? In what form to present them for
normal use by real people?

1. So far I've been using the approach of generating these wrapper
functions on the fly.  As a result, the IDL-ish file (markdown, or,
Google JSON) gets parsed *at runtime*. It's not a huge cost, but it's
_a_ cost. Plus it's a runtime file dependency. Bug or feature?

I've spent some brain cells pondering whether a macro should do a
(begin (define ...)), so that an API could be entirely mechanically
generated at runtime. But I'm at the edge of my macro comfort level.
Even to the point where I'm not even confident that a compile-time
macro should do this (??).

2. Part of me is starting to suspect seduction by the sirens of
runtime dynamism and macros. Instead, maybe real users want a library
that works, don't care how, but do want good docs and checks. Instead
of a runtime/macro proposition, a tool could emit a literal .rkt file,
plus maybe some head-start markdown and/or Scribble docs. To which a
package developer would apply some spit and polish, and push to PLaneT
and/or GitHub.

Re this second approach, note that the Google JSON API format appears
to have enough info to generate contracts for untyped Racket, as well
as Typed Racket interfaces.

I'm not sure if I'm explaining the choice clearly, but, any feelings
or suggestions about this?

On Tue, Oct 9, 2012 at 5:51 PM, Greg Hendershott
<greghendershott at gmail.com> wrote:
>> This is really neat! One thing I wonder is if there's a way to have
>> tighter integration with the module system.  Say, a #lang-based
>> Markdown-API language.
> Thanks for the idea. That had flitted through my mind and it may even
> be in the TODO file. It would be a great way for me to learn about
> making a #lang.
> I also noticed that the wiki for Sunday's HacketThon has an item about
> the Google API Discovery service and JSON format. I didn't know about
> that. There's a lot of overlap. Now I wonder if I should split this
> into two parts:
> 1. A web service "FFI" that uses Google's JSON format (i.e. the
> Hackathon project).
> 2. A markdown -> API JSON format tool, to make quick work of other web services.

Posted on the users mailing list.