Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refactor(graphql): GraphQL Public API Refactor + Documentation #3278

Merged
merged 34 commits into from
Sep 23, 2021

Conversation

jjoyce0510
Copy link
Collaborator

@jjoyce0510 jjoyce0510 commented Sep 21, 2021

This PR refactors the GraphQL API mainly addressing conventional consistency concerns. It also adds a bunch of new GraphQL API documentation! Rendered:

Also introduced auto-generated GraphQL Schema Reference documentation. These files are not checked in, but instead generated at build time.

Changes

  • Split monolithic GraphQL model file into 3 sub-schemas
    - entity.graphql: all CRUD operations against a given entity type (create, update, get, list)
    - search.graphql: all search and browse related graphql models
    - app.graphql: all UI specific graphql models (e.g. appConfig)
  • Added model descriptions for all GraphQL types and fields
  • Deprecate misc Entity "info" fields for standardized "properties" and "editableProperties" fields
  • Consistently accept urn, input arguments for each Update mutation to facilitate reuse of the Update input model in "create" APIs that will be coming soon.
  • Migrate "relationships" field input arguments to single wrapper "input" object, aligning with conventions across the app
  • Add Dataset "properties" field, deprecate root-level property fields (ie. description)
  • Miscellaneous renaming of models for consistency
    - TagUpdateInput -> TagAssociationInput
    - TermUpdateInput -> TermAssociationInput
    - TagUpdate -> TagUpdateInput
    - PolicyUpdate -> PolicyUpdateInput
    Breaking GraphQL API changes:
  • Remove the legacy string "tags" field from Dataset model
  • Migrate custom properties for Dataset from root level "properties" field to new properties.customProperties to align with other entity convention
  • Added GraphQL API Documentation generation + added to documentation website

Validated all changes locally.

Coming soon

  • Rich GraphQL Documentation on docs website
  • addOwner, removeOwner mutations
  • listEntity endpoints
  • createEntity, removeEntity endpoints
  • Consolidation in root-level key fields (urn, entity type, platform, name)
    Let us know which you'd like to see on our Slack :)

Checklist

  • The PR conforms to DataHub's Contributing Guideline (particularly Commit Message Format)
  • Links to related issues (if applicable)
  • Tests for the changes have been added/updated (if applicable)
  • Docs related to the changes have been added/updated (if applicable)

@jjoyce0510 jjoyce0510 changed the title refactor(graphql): GraphQL Public API Refactor refactor(graphql): GraphQL Public API Refactor + Documentation Sep 22, 2021
rm combined.graphql
touch combined.graphql
echo "Generating combined GraphQL schema..."
echo "# Auto Generated During Docs Build" >> combined.graphql
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why not just do a single > and drop the rm?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

just consistency w/ the lines below?

Copy link
Contributor

@shirshanka shirshanka left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We finally have a public API! Really excited to see how the community responds.

@shirshanka shirshanka merged commit 106be09 into datahub-project:master Sep 23, 2021
xdl pushed a commit to G-Research/datahub that referenced this pull request Oct 4, 2021
xdl added a commit to G-Research/datahub that referenced this pull request Oct 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants