faxman

Following on our previous discussion on HN [1], we've gone ahead and implemented a REST interface for our online fax service, where we previously only had a SOAP API.

Documentation [2] is 90% complete, so this might be a good time to get your feedback if we're doing it right.

As always, brutal honesty appreciated!

--------------

[1] http://news.ycombinator.com/item?id=3467287

[2] http://www.interfax.net/en/dev/rest/reference

InterFAX is an online fax service provider which is popular with developers because of its API. Up until now we've only had a SOAP API, and due to popular demand, we're coming out with a REST API. I would appreciate your comments on how we're doing.

The service is documented at http://www.interfax.net/en/dev/rest/reference (this is a deep link; the link hasn't yet been published publicly), where there's also access to a little developer's guide.

The service is live on a pilot server. To play around with the service, register by clicking on any one of the "Get Started" buttons which lead to www.interfax.net/en/dev/register. Because the service is on a pilot server, any live code needs to go to endpoint https://rest-pilot.interfax.net instead of the documented https://rest.interfax.net .

Pre-empting some comments that are likely to be raised:

- Samples for various languages will be released at a later stage. However, cURL and raw HTTP samples will be available for every operation before the API gets released.

- A "Getting Started" page is in the works.

Fire away!

My company has been offering a SOAP-based API since around 2002. We recently ran a survey on our site in which a full 25% of visiting developers said that SOAP is a show-stopper for them and that they would prefer REST, even though we provide full code samples in various languages for our SOAP interface.

Ever mindful of our clients' wishes, we've begun designing a REST interface. We've been trying to adopt the best practices of API providers out there, and we're planning to provide client libraries for the most popular languages as well.

This will take us a good few months, designing objects and operations, implementing the service, creating code samples, etc. At the end of this process, a PHP developer, for example, will be able to send a fax through the REST API by using this code:

       <?php

       require('Interfax.php');
       $client = new InterfaxClient($username, $password, $faxnumber, $texttofax, $filetype);
       $result = $client->SendFax;  
       echo $result;

       ?>

instead of this code:

       <?php
        
       $client = new SoapClient("http://ws.interfax.net/dfs.asmx?wsdl");
        
       $params->Username  = $username;
       $params->Password  = $password;
       $params->FaxNumber = $faxnumber;
       $params->Data      = $texttofax ;
       $params->FileType  = $filetype;
        
       $result = $client->SendCharFax($params);
        
       echo $result->SendCharFaxResult;  
       ?>

which is, effectively, the same. The complexity of interfacing to the API is hidden in a custom library instead of a SOAP library. Which brings me to ask myself "what's the point"? Where does the advantage of having a REST interface come into play?

PostalShout is a web-to-post service geared towards businesses. It allows them to send letters from any word processor with no installations.

www.postalshout.com

Our previous startup is a developer-targeted, API-accessible web-to-post service called PostalMethods. We noticed that it was attracting quite a bit of "unqualified" traffic, in the sense that it wasn't just developers signing up, but also end-users needing to send business correspondence from their desktops. End-users aren't really well-served by that site because it quickly deteriorates into geek-speak, so we decided to try and give them a better home.

We researched end-users' use of the site and found a lot of them were sending plain MS Word or PDF files via email. Hoping to ride on that trend, we've come out with PostalShout which targets business users who need to post mid-size quantities (hundreds to low thousands of letters per month) of postal mail. The service lets them post transactional letters - invoices, reminders, simple marketing material, collections letters, etc. - directly from their word processor.

Does our targeting come across? Is it clear what we're selling? Are the benefits clear and compelling? Does it appear easy enough to register? Would any element in the site keep a person from registering? Are we missing anything?

Gloves off; let's hear it!

P.S. If you'd like to test the service for real, drop me an email at the address in my profile and I'll send you a $10 coupon.