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?
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?