Add @api to mark elements of our public API

[spawnia]

Is your feature request related to a problem? Please describe.

Currently, we have no hard rule of what we consider breaking changes. Although many methods are public, we have not really specified exactly which are stable.

Describe the solution you'd like

Use the @api PHPDoc tag to mark elements that we consider part of the public API and guarantee not to change until the next major release.

[yaquawa]

How about defining them as interface?

[spawnia]

Interfaces are great when we have classes that the user may want to plug into or subsitute the implementation.

Not all classes or methods we provide fall under that category. The ones that we provide for direct use should be kept stable if possible, and we can mark that with the @api PHPDoc

[georgeboot]

Isn't the point of GraphQL that you don't (have to) do versioning? You should just add new fields, and if you ever need to deprecate an old field, you should mark it so: @deprecated.

Also, to hide it from the public api, you should be able to use @hidden.

Note: these directives are NOT supported in lighthouse at this moment. See #408

[spawnia]

@georgeboot This issue does not have anything to do with the GraphQL schema. It is about adding PHPDoc annotations to our code.

[georgeboot]

@spawnia apologies, I misunderstood the issue. I thought was about the GraphQL API having annotations, while it was actually about the internal code needing the annotations so people can extend it.