search

alphagov / data-standards-authority

Collaboration space for working on data standards and guidance for the DSA
https://alphagov.github.io/data-standards-authority/
Other
24 stars 11 forks source link

Re: 'APIM - 02 - Design' #120

Open jamietanna opened 3 years ago

jamietanna commented 3 years ago

Feedback on 'APIM - 02 - Design' (https://alphagov.github.io/data-standards-authority/guidance/apimanagement/APIM-Design.html)

Is there something we can add here about the fact that this can help catch common errors or pitfalls in API design before someone gets most of the way through implementing, and it's then super costly to correct it?

-API design guidance reduces friction by providing a framework within which a developer can start to work.

-It’s important to provide explanations for design choices. Being open with the decisions behind the guidance increases developer trust and helps get them on board with the process.
+API design guidance reduces friction by providing a framework within which a developer can start to work, but can be seen initially as a roadblock.

+It’s important to provide explanations for design choices, and educate developers on common pitfalls that could be faced without following these standards. Being open with the decisions behind the guidance increases developer trust and helps get them on board with the process.

Some content suggestions:

-Setting out decisions like these in a central place helps development teams get started on projects more quickly and with less effort. Some organisations simply keep these guidelines on a central document store or git repository, while some have dedicated tooling. Various tools are available to store and share API specifications, many of which have an open source version which allows you to try them out.
+Setting out decisions like these in a central place helps development teams get started on projects more quickly and with less effort. Some organisations simply keep these guidelines on a central document store or git repository, while some have dedicated tooling or "getting started" templates. Various tools are available to store and share API specifications, many of which have an open source version which allows you to try them out.
 Tooling like this can provide functionality including:

 - specification support
 - real time validation
 - auto-completion
-- auto generated documentation
+- auto-generated documentation
+- auto-generated API clients
+- auto-generated data classes