XAPI

As I said in the last post regarding build tools in haXe, I've been working in XAPI.

To put it simply, XAPI (Ximple API, the "x" is mandatory on haXe projects, you know?!) is a higher level API for haXe backends. Tu put it even simpler, that means doing more with less lines of code.

So, what can it do?



You can do all this already with "plain" haXe, XAPI only simplifies how you do it. Sometimes it also prevents developers for making mistakes. Two quick samples:

Writing content to a text file using XAPI:

[code lang="actionscript"]xa.File.write('myFile.txt', 'haXe rocks');[/code]

Using plain haXe:

[code lang="actionscript"]var f = neko.io.File.write('myFile.txt', false);
f.writeString('haXe rocks');
f.close();[/code]

[BTW, the opposite is not true, there's neko.io.File.getContent() which I didn't know about and used to use for this example. And also, turns out the PHP package has php.io.File. putContent()]

Checking if a file exists using XAPI:

[code lang="actionscript"]var exists = xa.File.isFile(null);[/code]

Using plain haXe:

[code lang="actionscript"]var exists = !neko.FileSystem.isFolder(null);[/code]

So, there's no "isFile()" call in the API, plus using haXe alone you would get an exception because you are passing null (in real world you would never pass null on purpose, but it happens that you pass a variable that is), whereas in XAPI I check for null and, if it is, it just returns false. I think that's how it should work and I reported it as a bug, but it won't get fixed :/

Those are the little and not so little additions that XAPI provides to the Std API. To get full details, just install and check out the docs. Simplest option is installing via haxelib (haxelib install xapi), but you can read installation instructions on the wiki.

HippoHX's API is the mother of XAPI. That's when I first decided that I was going to expose a slightly different API that **I** thought it was simpler. See those stars around "I"? They are important. You see, this business of building APIs is very, very subjective. I honestly think it's much like designing. You need to know your target audience, one size doesn't fit all, and there's a great deal of taste involved.

XAPI is an API for developers like me, with the same needs I have, etc., etc. I'm fine with that, I have no plan to dominate the world (yet), and I've built XAPI to help me on my own projects. I open it to the world so hopefully a) other devs will benefit and b) people will help me fix bugs.

What the future is?

Turns out XAPI is almost feature complete because I want to keep it simple. I want it to be easy to use and I don't want to target every single project out there, because that's what the Std API is for. When we were discussing on the list about what XAPI could do,Jonh de Goes came up with an interesting idea about building some kind of "general file system wrapper" API where each "node" could be a file on your system, in the cloud or somewhere else (read it here). Well, that sounds like an awesome project, but out of the scope of XAPI.

On what can only be described as sweet irony, he also was the person who convinced me NOT to do it when I read his series of posts about writing Good APIs (1, 2, 3, 4. Extra Ball, also read his post about Dispersed Development).

Sweet Spot Saturation Rule

"By letting go of the power users, they achieve high usability (this is not always an inevitable tradeoff, but at the very least, simpler applications are easier to make usable than more complex applications"


And that's exactly what I'm planning to do. By not implementing the general file system wrapper he proposes I'm going to let go power-users like him on behalf of mid-users like myself. I hope it pays off resulting in a very simple to use API. Time will tell.

One thing that I'm thinking about is custom exceptions, though. At the moment if the Neko VM finds a problem it raises an exception which I'm not sure we know the type of. So catching them in XAPI and raising new ones to which we know the type I think would help a lot. Ideas welcome, btw.

Is XAPI for you?

Well, depends on the type of projects you face and the kind of developer you are.

If you build for backends (php, cpp, neko), it might interest you.
If you are rather new to haXe, it might interest you.
If you develop build tools, it might interest you.
If you are wiling to sacrifice some flexibility to gain simplicity, it might interest you.

And to wrap up, thanks to Ian Thomas, he was the first one suggesting such a project more than a year ago. I might need some time, but I do deliver : )

Back to index