Fuchsia

Fuchsia API Design Document template

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.

Summary

A one paragraph summary of your change to the Fuchsia API.

Goals and use cases

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.

Design

This section contains the technical details of your API design.

This section contains the following:

  • A high-level description of your approach, including:

    • The key choices that you’ve made in your design.
    • The actual code definition of the API, such as the FIDL definition of an interface.

  • A Gerrit change link that contains the code for your API:

    • Your API design should conform to the API readability rubric for the language that you use to write the API. The interface should be fully documented at this stage but it does not need to be implemented.

  • 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.

Unknowns

This section answers the following questions regarding your design's assumptions:

  • What information are you missing that might help improve the design?
  • Are there areas of your design that could be improved?
  • Which parts of your design are you most interested in receiving feedback on and why?

Usability

This section answers the following questions regarding the usability of your API:

  • Are the semantics of your API intuitive from its signature(s)?
  • Have you designed the appropriate extensions points to allow for the future evolution of your API?
  • Does your API behave similarly to other Fuchsia APIs that do similar things?
  • How does your API behave compared to similar APIs for other platforms?

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.

Testing

This section answers the following questions regarding your API's approach to testing:

  • How do you plan to test your API?
    • You might have unit tests for your implementation, but you might also want a medium-size test that exercises your implementation through your API.
      • Consider using lib/component/cpp/testing.
  • If developers were to rely on your API feature, how would they test their code?
    • Consider providing a mock implementation of your API that clients can use for testing purposes.

Performance considerations

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:

  • Does your API involve a large number of round-trips across a process or thread boundary?
  • Does your API involve blocking on a remote process or thread?
  • Does your API involve copying large amounts of data?
  • How many queries per second (QPS) do you expect your API to receive?
  • How much data do you expect a typical query to transport?

Security considerations

This section answers the following questions regarding how your API design considers security:

  • Does your API expose security-sensitive information?
  • Does your API let its users manipulate security sensitive resources?
  • Are the users of your API isolated from each other?
  • Does your API respect an object-capability discipline?
  • Does your API encourage your users to use your API securely?
    • Does your API encourage time-of-check to time-of-use (TOCTOU) vulnerabilities?
    • Does your API clearly separate any control planes from any data planes?

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.

Privacy considerations

This section answers the following questions regarding how your API design considers privacy:

  • Does your API expose privacy-sensitive information?
  • Does your API involve any personally identifiable information?
  • Does your API involve any device identifiers?
  • Does your API provide users control over how information is shared?

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.

Drawbacks and alternatives

Your API design document is expected to answer the following questions regarding how you've considered drawbacks as well as alternative implementations:

  • Are there any disadvantages to your API design?
  • What alternative designs did you consider?
    • Why aren't you using these alternatives?
    • Are there trade-offs or scenarios where these alternative designs may be appropriate?

Submit your API Design Document

To submit your API Design Document, do the following:

  1. Duplicate this markdown file.
  2. Edit the contents of that duplicate markdown file to include the answers to the template.
  3. Save your markdown file with a hyphenated name of your choosing.
  4. Submit your API Design Document markdown file by following the steps Contribute changes.

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.