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

General Feedback on API Standard #34

Open
bradprosser opened this issue Jul 6, 2020 · 0 comments
Open

General Feedback on API Standard #34

bradprosser opened this issue Jul 6, 2020 · 0 comments

Comments

@bradprosser
Copy link

I’m working on a project in Services Australia and we’ll be implementing a number of RESTful APIs. Some colleagues referred us to this standard:
https://api.gov.au/standards/national_api_standards/

For what it’s worth, I found it very good. I thought I’d share some relatively minor feedback just to help improve it further.
I’ve bolded below one question that I’d like to confirm, as we’re currently specifying such examples in APIs we’re designing.

WoG API Requirements
More advice or examples on what the fill in for the legal section of a spec would help.

Naming Conventions
Why is snake_case preferred over camelCase?
Assume _links is SHOULD instead of MUST, considering maturity level doesn’t have to be 3?

API Versioning
X-API-Retire-Time – description is wrong (deprecated instead of retired).
X-API-Retire-Time – should this be added to /version end point?
Version example has /docs instead of /api-docs as mention elsewhere in the standard

API Requests
You could add some advice about which RFC (5789 or 6902) to use for PATCH

Query Parameters
Pagination hyperlink is wrong, points to itself instead of another page.
Like keyword is missing from supported operators
Advanced filtering examples are unclear and resemble pseudo code. Is this a valid example?
filters=custId=12345,67890,23456&start_date=2019-10-02+10:00&end_date=2019-10-02+10:00&group_codes=ABC,DEF,XYZ

API Responses
Does Date header have to be GMT, or can something like UTC+10 be used instead?

API Security
Assume basic auth can also support username:password?

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

No branches or pull requests

1 participant