Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
GUI opened this issue Nov 13, 2014 · 1 comment
Open

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

GUI opened this issue Nov 13, 2014 · 1 comment

Comments

@GUI
Copy link
Member

GUI commented Nov 13, 2014

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

GUI pushed a commit that referenced this issue May 14, 2015
@derekwmiller
Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants