5 ms·

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 A

by ammmir 14y ago

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 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.

kategleason 14y ago
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 k@eligibleapi.com so that I can provide you with a full data set of JSON response.
- sriramk 14y ago
  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.
- gvnonor 14y ago
  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.
  - kategleason 14y ago
    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
tylermenezes 14y ago
> 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.
- wilmoore 14y ago
  An Oauth2 token via http header works very well. Of course, you'll want to send only encrypted requests.
babel 14y ago
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.

by ammmir 14y ago

kategleason 14y ago

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 k@eligibleapi.com so that I can provide you with a full data set of JSON response.

sriramk 14y ago
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.
gvnonor 14y ago
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.
- kategleason 14y ago
  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

tylermenezes 14y ago

> 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.

wilmoore 14y ago
An Oauth2 token via http header works very well. Of course, you'll want to send only encrypted requests.

babel 14y ago

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.