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