Feb 19, 2019
Discuss feedback from Tech Panel on:
New: API implementation guidance
Updated (v1.1): API Guidance
Some edits made throughout
Updates to Error Handling section
Updates re: JSON schemas in the Versioning RESTful APIs section and the API Definition section
Additional concepts that would benefit from similar guidance.
Overall, it is nice to see guidance maturing and including modern recommendations and best practices.
Sections of the guidance that connect abstract principles with concrete examples at CDC -- these are very helpful to make these principles more understandable.
Showing examples of things we can leverage without reinventing the wheel could also improve buy-in of this guidance
Action: Take another pass through existing guidance to see if there are other such examples we can add.
In API Implementation Guidance, it would be helpful to link to examples of demonstrated workflows / best practices for implementing APIs with existing frameworks.
Action: Look for and link to examples using Java, .NET, R (plumber library)
Question: why is there a recommendation to render YAML in the API Design Guidance?
To clarify: the recommendation is to use YAML to represent metadata about the API, not as a data exchange format
Suggested next steps for additional guidance:
How to broaden the audience for existing guidance? Could we tie it to the strategic IT plan and/or link to it from other documents to improve discoverability?
Action: Engage with Chief Public Health Informatics Officer for suggestions on bringing this guidance to more stakeholders within CDC.
Next Tech Panel meeting to be scheduled as and when it is needed.
Pulled from above discussion notes: