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.
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.
* 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.
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.
* 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):
* 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.