Skip to content

Cross-language API/IDL support (GraphQL, Thrift, Protobuf)

Created by: sqs

We will be adding support for cross-language API/IDL systems to Sourcegraph, in order of priority:

  • GraphQL (partially done)
  • Thrift
  • Protobuf

You will be able to see hovers with documentation, go to definition, find references, etc., in API/IDL definition and code that is generated from them.

Use cases

  • As a developer who is consuming a service, I want to see usage examples of a service's method so I can quickly see how to use it.
  • As a developer who is consuming a service, I want to see values of a service's type so I can quickly see how to construct such a value.
  • As a developer who is consuming a service, I want to go to the implementation of a service's method to debug an issue I encountered when my client is calling the service.
  • As a developer who maintains a service, I want to see call sites of a service's method to understand how it's being used (for future improvement planning, backcompat/deprecation, capacity planning, and identifying common mistakes).

What makes this hard today:

  • The IDL schema, service, and clients are usually scattered in different locations (or even different repositories), so it's not always clear where to start looking.
  • The IDL schema and service are often maintained by a different team than the clients, so there is no single person who necessarily knows the answers.
  • The IDL schema is usually written in a custom language that has poor or uneven tooling support (.graphql, .thrift, .proto).
  • Service method and type names are usually not globally unique (e.g., Lookup or Delete), so text search yields many false positives.
  • The service and clients are sometimes written in different programming languages, so:
    • Code search wouldn't necessarily find all hits (e.g., if the names are inflected differently in generated code)
    • Code intelligence for a single language wouldn't find all references or definitions
  • Generated code is often used in these scenarios, and it may be:
    • Complex (and its derivation from the original schema may not be obvious)
    • Not checked into source control (so code search would not find it and code intelligence would not work on it)
  • Often it's not possible to know (from the code alone) which service version a client is accessing.

Customers: