Skip to content

Public API surface

Not every exported API from the package is considered a public API. Not every use of it is considered to be public use. Similarly to the Angular public API surface, non-public API members or use cases should not be used.

Really, do not use non-public APIs

Non-public API or non-public uses of it are not supported use cases. Therefore breaking changes may be introduced in those cases without the formal process for those (i.e.: a major release)

Public, but not production ready APIs: alpha and beta APIs

Some APIs may be public, but in alpha or beta state. You may identify those because any of these reasons:

  • API documentation contains an @alpha or @beta tag
  • A warning in the API reference docs about the alpha or beta state of it.

You can experiment with those. But beware that they may change based on feedback received.

They are not ready and should not be used in production environments.

A @beta API is more mature than an @alpha API.

Some APIs may be marked as beta but be alpha

Somehow API Extractor hides methods from a class if the class or method is marked as @alpha when generating the documentation model JSON. So @beta is used in order to expose the method anyway.

Exclusions

Everything exported is considered a public API except...

Non-public API members

Some exported API members from this package are not intended for public use.

Those can be easily identified because one or more of these reasons:

  • API documentation contains the @internal tag.

  • API is a class method marked as private. Same happens with Angular public API surface.

  • API name starts with an underscore _. Same happens with Angular public API surface.

  • API member does not appear in documentation

Those are not public API members. They are exported only to be used internally.

You may request for a non-public API to be made public

If you consider you'd benefit from a non-public API, please raise a new discussion in GitHub. The API can be transitioned into a public one if that's helpful.

Private and internal APIs

Inside the world of non-public API names there are two kinds: the internal and the private ones.

  • Internal APIs: start with just one underscore _. They are mainly exported to share APIs internally between the package's multiple entrypoints. Mainly exported by the core package to be used amongst the rest of package's entrypoints / modules.

  • Private APIs: start with two underscores __. They are mainly exported to be used by other APIs in the same entrypoint or for (unit) testing purposes.

Using inheritance with exported API classes

Similar exclusion to Angular public API surface's one:

Quote

Extending any of our classes unless the support for this is specifically documented in the API reference.

However, we can go a bit further and say it's not in the nearby plans to support that. APIs are designed to favour composition over inheritance. Hence, extending any of the exported classes won't be a supported use case for now.

Constructors of injectable classes

Similar exclusion to Angular public API surface's one:

Quote

Constructors of injectable classes (services and directives). Use dependency injection to obtain instances of these classes

File imports

All public APIs will be exported from the module's entrypoint. If they're not, they are non-public. Or we've messed up something. Things happen 🤷

Similar exclusion to Angular public API surface's one:

Quote

Any file/import paths within our package except for the /, /testing and /bundles/* and other documented package entry-points.