search

NREL / developer.nrel.gov

An issue tracker for NREL's APIs available at https://developer.nrel.gov
43 stars 39 forks source link

Use of coded values in the API calls and responses #7

Open GUI opened 9 years ago

GUI commented 9 years ago

Feedback from our API Usability Testing: Using less code values or more descriptive code values would make the APIs easier to use. An example of coded values can be seen in the alt fuel stations api. There you would pass in status=E for only open stations, which is not descriptive or intuitive. Something like status=open would be easier to understand. Some of our other code values might be slightly more descriptive, but they could definitely use improving (for example, in fuel types, CNG is a common abbreviation for compressed natural gas, but BD isn't necessarily as obvious for biodiesel).

derekwmiller commented 5 years ago

It also helps when the values listed in the API documentation match what is returned in the API.

For example, alt fuel stations in Oregon return the following unique values for 'groups_with_access_code': Private - Government only PLANNED - not yet accessible (Private) Private TEMPORARILY UNAVAILABLE (Public - Credit card at all times) Public - Call ahead Public - Credit card at all times Public - Card key at all times TEMPORARILY UNAVAILABLE (Public - Call ahead) Public - Credit card after hours PLANNED - not yet accessible (Public - Credit card at all times) Public Public - Card key after hours

Of those values, the following are not in the API doc and therefore unexpected in the return. PLANNED - not yet accessible (Private) TEMPORARILY UNAVAILABLE (Public - Credit card at all times) TEMPORARILY UNAVAILABLE (Public - Call ahead) PLANNED - not yet accessible (Public - Credit card at all times)

Also, case matters. The response and the docs don't match in regards to case (Public - Call ahead vs Public - call ahead)

Thanks.