News for hackers. Stuff that matters.
Re:Show HN: Eligible API for 700+ Health Insurance Companies by ammmir on Saturday August 11, 2012 @12:01AM (#4369387)
I applaud the initiative, but I think the JSON needs to be friendlier.

* Use REST.

* Use HTTP Basic auth instead of cluttering the URL query string with the API key.

* Use ISO 8601 for dates, no exceptions.

* Use lower_case or lowerCamelCased keys.

* Don't use spaces or other non-alphanumeric/underscore characters in keys, otherwise you can't easily index child objects with dot notation in many languages.

* Instead of liberally using dictionaries, use arrays with a type field. For example (I couldn't finish the example because the example JSON on your site is indented too poorly to comprehend):

    active_coverage: [
      {
        title: "Item #1",
        description: "Choice Fund HRA Open Access Plus",
        free_text: "Member is in network based on NPI ID provided in request",
        ...
      }
    ]
* Why are percentages expressed as a string? Instead of ".1" which will need to be parsed again by the consuming app, use a raw number, or to avoid floating points, multiply by 100 to ensure whole numbers.

* Same goes for balance, make it a number (use cents to avoid floating points), and provide units like "USD".

The JSON example at https://eligibleapi.com/overview/how-it-works is incomplete and invalid. I'd be interested in seeing the entire JSON envelope to see how to actually get at the data and what other metadata is exposed.

This looks like a straight up EDI translation into JSON, and thus not natural at all. I'd try to abstract it out a bit more into what people might use it for, and build a truly consumable REST API.

Re:Show HN: Eligible API for 700+ Health Insurance Companies by kategleason on Saturday August 11, 2012 @12:14AM (#4369412)
can we hire you?

I love your feedback, we know this is still raw (early beta) but its great hearing constructive suggestions. Please email when you have a chance [email protected] so that I can provide you with a full data set of JSON response.

Re:Show HN: Eligible API for 700+ Health Insurance Companies by sriramk on Saturday August 11, 2012 @03:36AM (#4369679)
Actually, as someone who has designed/run a high scale REST API, I have a slightly blasphemous view on this - that the RESTful-ness of the API doesn't matter.

You're better off trying to control how the various language bindings look like and focusing on making core scenarios be as clean as possible code-wise. That's what the developers building on top of your API will actually see and deal with on a day-to-day basis.

Re:Show HN: Eligible API for 700+ Health Insurance Companies by gvnonor on Saturday August 11, 2012 @01:22AM (#4369522)
In case ammmir decides takes you up on your offer, I'd advise him to ensure that a contract is in place before committing to do any work.
Re:Show HN: Eligible API for 700+ Health Insurance Companies by kategleason on Saturday August 11, 2012 @01:36AM (#4369539)
Waiting for that bad boy. In case anyone is curious of what gman is referring to you can read my response here katgleason.tumblr.com
Re:Show HN: Eligible API for 700+ Health Insurance Companies by babel on Saturday August 11, 2012 @09:31AM (#4370046)
Thanks for your feedback ;-)

* I'm not sure what you mean with being REST...

* I thought that a secret key part of the query string (together with the usage of HTTPS) is simpler. But, I might be more a question of personal preference, meaning that we should provide different way to authenticate ;-) I will put this on our to-do list.

* I fully agree, my mistake, I will check this!

* That makes sense... I personally have a preference for the underscores, we will discuss that at Eligible.

* Idem.

* To be fully honest, it has been an internal debate: "use or not use array" ;-) I personally wanted to use them... so, thanks for your feedback ;-)

* That makes sense... we will discuss that at Eligible.

* Usually, when I design a grammar, I always want to have the UOM next to any number! BUT, in this case, I did not pay enough attention to it... This Eligibility story is - according to my current knowledge - a US and only a US story.

* You are right! Following other comments, we might soon provide a public test API key that will return a predefined anonymized JSON answer so developers can hack the API straight away ;-)

* I can tell you that our JSON structure is already quite different from the flat raw X12 271 format. But, we might have lost a bit our track to make it as simple as possible to consume... Any suggestion is welcome ;-)

Thanks again for your feedback, please wait to get a full JSON instance - via updated documentation and/or the test API key - and carry on with such constructive feedback.

Re:Show HN: Eligible API for 700+ Health Insurance Companies by tylermenezes on Saturday August 11, 2012 @05:14AM (#4369783)
> Use HTTP Basic auth instead of cluttering the URL query string with the API key.

Most APIs I've seen have moved off of HTTP basic auth, usually into including it as a separate header. Doesn't necessarily mean much, but it does mean it's not standard practice by any means.

Re:Show HN: Eligible API for 700+ Health Insurance Companies by wilmoore on Friday August 17, 2012 @12:43PM (#4397349)
An Oauth2 token via http header works very well. Of course, you'll want to send only encrypted requests.