Skip to content

The project should better demarcate what is API and what is not #284

Closed

Description

@bbakerman

Currently it is not crystal clear what is API and what is not.

Clearly top level classes such as GraphQL and ExecutionStrategy are API

But what about graphql.execution.Execution or graphql.execution.ValuesResolver. Are they API or implementation detail?

If we had to add new aspects to these classes and changed constructors etc are we breaking consumers?

I suggest that the API be made more clear.

Annotations are a great way to do this. The project could have 3 new annotations

@publicapi (things you can call and wont change)
@PublicSPI (things you are meant to implement)
@internal (public things that are not API and may change)

This will allow the project to better keep semver sematics while evolving as necessary.

Activity

  1. jimexist commented on Dec 26, 2016

    @jimexist
    Contributor

    regarding @Internal i think putting internal in package name is a good practice

  2. bbakerman commented on Dec 28, 2016

    @bbakerman
    MemberAuthor

    I agree on .internal in the package name as well as .api in the packages however that would be a major breaking change.

    Ideally it would be

     graphql.api.AnApiClass
    

    and

    graphql.internal.InternalImplementationClass
    

    the use of annotations are a way to not break current API while better documenting what is API

  3. andimarek commented on Apr 8, 2017

    @andimarek
    Member

    Because we are planning for a breaking change release I suggest that we use that to try to make it more clear what api vs internal is.

    But I think moving everything is not acceptable imho. Breaking stuff should be limited to what we think is really necessary. Annotating seems fine.

  4. added this to the 3.0.0 milestone on Apr 8, 2017
  5. andimarek commented on May 2, 2017

    @andimarek
    Member

    I like the idea to add two annotations @PublicApi and @InternalApi for example.

  6. andimarek commented on May 6, 2017

    @andimarek
    Member

    First shot: #411

  7. andimarek commented on May 14, 2017

    @andimarek
    Member

    we added annotations in #411 ...closing it therefore now: we will add the annotations as we go.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions