Add README.
[software/guile-aws.git] / README.org
1 Guile AWS is pre-alpha software. At the very least it’s yet another demonstration that Guile’s compiler tower can be used to generate an embedded domain specific language from JSON specifications.
2
3 The DSL Guile AWS produces is unpolished and thus pretty repetitive and ugly. Even in the simplest of cases it is verbose:
4
5 #+begin_src scheme
6 ,use (aws api s3-2006-03-01)
7 ,pp (ListBuckets #f)
8
9 #+end_src
10
11 The output is even worse as it is currently unprocessed SXML.
12 It may not even work at all, because the AWS APIs are all a little different.
13
14 Considering all these caveats there are a couple of obvious things to work on:
15
16 ** Use the requestUri
17 Since testing began with the EC2 API which only provides operations with the same =requestUri= of “/” the =(aws request)= module never implemented any handling of the =requestUri= field. The S3 API, however, is full of fancy URIs such as ="/{Bucket}/{Key+}?restore"= — it is not clear how to interpret the placeholders.
18 ** Create aliases
19 The S3 API (for example) defines aliases for some operations, such as “PostObjectRestore” for “RestoreObject”. The compiler should process the “alias” field.
20 ** Record possible errors
21 The S3 API (for example) defines possible error names. While their shape is not specified anywhere we should generate values for these error conditions.
22 ** Do not require an input
23 Some operations don’t require any input, such as =ListBuckets=. For operations like that we should not be forced to specify #F.
24 ** Process output shapes
25 We generate types for all defined shapes — including output shapes — but we don’t mashall the output SXML into appropriate Scheme values yet.
26 ** Turn errors into Scheme conditions
27 This is easier said than done because different APIs return different kinds of errors.