This template details the sections that should be included in your API design document as well as the questions that should be answered by your API Design Document.
A one paragraph summary of your change to the Fuchsia API.
Your API design document is expected to answer the following questions regarding your API's use cases:
What problem does this API or API feature solve?
What would users of your API be able to accomplish?
This section acknowledges that there is more than one solution that could resolve the problems your API is intended to fix. Construct your “Use cases” section in a way that doesn’t presuppose that the design proposed by your document is the only correct way to solve those use cases.
This section contains the technical details of your API design.
This section contains the following:
A high-level description of your approach, including:
A Gerrit change link that contains the code for your API:
An explanation of the choices behind your API design and why you’ve made those design choices.
An explanation of how your API might evolve in the future.
This section answers the following questions regarding your design's assumptions:
This section answers the following questions regarding the usability of your API:
A good framework for thinking through the usability of your API is to write example programs that use your API. That exercise gets you thinking about how users experience your API and lets you experience any potential drawbacks of your design.
If you find your API difficult to use while writing these examples, consider revising your API to improve its usability. Your users are end-developers. They should be key stakeholders when you consider how to design your API.
This section answers the following questions regarding your API's approach to testing:
There is often a tension between performance and usability. The performance considerations for an API often vary by the frequency with which the API is used. This section should describe the choices that you’ve made to balance these concerns. Consider consulting the API readability rubric for language-specific guidance about how to balance these concerns.
This section answers the following questions regarding how your API design affects performance:
This section answers the following questions regarding how your API design considers security:
If your API has non-trivial security considerations, you should consult with the security team and go through a formal security review. If this is the case, contact the API council about requesting a security review.
When a security review is performed, provide a link to your security review in this section.
This section answers the following questions regarding how your API design considers privacy:
If your API has non-trivial privacy considerations, go through a formal privacy review. When a privacy review is performed, provide a link to your privacy review in this section.
Your API design document is expected to answer the following questions regarding how you've considered drawbacks as well as alternative implementations:
To submit your API Design Document, do the following:
After your Design Document has been submitted, it is reviewed by the API Council. For more information on the API Design Document review process, see the Fuchsia API Council Charter.