services/api_standards.md

# API Standards for Foundation Services

In creating and maintaining the public-facing structure of a foundation service,
you should hold yourself to several first-order goals:

* The purpose of the service should be readily apparent.
* The supported usage models of the service should be easy for a new
  consumer to understand.
* The service should be consistent with other foundation services.
* From the API documentation and tests, it should be feasible
  to develop a distinct implementation of the service (i.e., without having to
  delve into the internals of the current implementation).

Below we outline concrete standards that aid in achieving the above goals.

## Naming

* Strive to give your service a name that makes it immediately obvious what the
  service is for ("network", "metrics").

* Avoid the usage of "Service" in interface names. While the term "Service" is
  overloaded in Chromium, in the context of //services it has a very specific
  meaning and should not be overloaded.

* Strive to avoid conceptual layering violations in naming -- e.g., references
  to Blink or //content.

* Use the names "FooClient" and "FooObserver" consistently in interfaces. If
  there is an expected 1:1 correspondence between Foo and its counterpart, that
  counterpart should be called FooClient. If there is an expected 1:many
  correspondence between Foo and its counterparts, those counterparts should be
  called FooObservers.

## Documentation

* Every service should have a top-level README.md that explains the purpose and
  supported usage models of the service.

* Every public interface should be documented at the interface (class) level and
  at the method level.

* Interface documentation should be complete enough to serve as test
  specifications. If the method returns information of a user's accounts, what
  happens if the user is not signed in? If the method makes a request for an
  access token, what happens if a client makes a second method call before a
  first one has completed? If the method returns a nullable object, under which
  conditions will it be null?

* Strive to avoid your documentation being too specific to a given client.

## API Shape

* Strive to avoid molding your API shape too specifically to the needs of a
  given client. Most foundational services should make sense even in a
  Chrome-less system environment. A good test is: Would your service's APIs seem
  sensible to users who don't have knowledge of Chrome's specific needs?

* If a given interface Foo requires "construction parameters" (e.g., the client
  must give it a FooClient before calling any methods), provide a FooProvider
  interface with a GetFoo() method that takes in the relevant construction
  parameters. This approach eliminates the possibility of a badly-written (or
  malevolent) client calling methods on a partially-constructed Foo. To be
  concrete:

    ````
    // NO: Client will have access to partially-constructed Foo.
    interface Foo {
      SetClient(FooClient client);
      ...
    };

    // YES: Foo will be completely constructed before client has access.
    interface FooProvider {
      GetFoo(Foo& request, FooClient client);
    };
    interface Foo { ... };
    ````

* In the absence of specific guidance, strive for consistency with surrounding
  interfaces and with interfaces in other services.

## Testing

* Use service tests to test the public interfaces exposed by your service.

* Every public method should be covered by at least one service test. Strive
  to have your tests enforce your documentation (corollary: if you can enforce
  your documentation without any tests, improve your documentation :).

* Think of these tests as a form of "compliance tests": They should be written
  in such a way that engineers with a distinct implementation of your
  APIs should trivially be able to run your tests against their implementation.
  Notably, try to avoid relying on implementation details of the service in its
  tests.

* Related to the above, aim for a high degree of coverage with these tests. If a
  reimplementation passes your tests, you should have a high degree of
  confidence that it will be usable by your consumers.

## Appendix: Responsibility for Upholding These Standards

The responsibility for holding these standards is shared across
//services/OWNERS, individual service OWNERS, and services developers:

* //services/OWNERS own the standards themselves and are responsible for
  ensuring that quality and consistency are maintained across //services.
* Individual service OWNERS are responsible for ensuring that their service
  adheres to these standards.
* Service developers are responsible for ensuring that their CLs adhere to
  these standards (and thus making life easier for the OWNERS that must review
  these CLs :).

We expect that these standards will evolve over time. If you encounter a tricky
situation not covered here, please send an email to services-dev@. Similarly, if
you see inconsistency or violations of the standards, please file a bug and CC
relevant OWNERS (i.e., of the service in question and/or //services/OWNERS).