palantir / palantir/conjure-java

Unexpected discrepencies between FooService and FooServiceBlocking when introducing new API versions

Open
#960 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
39
Forks
49
Avg merge
8h 22m
Merged PRs (30d)
32

Description

What happened?

If we start/release a FooService defined as such:

services:
  FooService:
    name: Foo Service
    package: com.palantir.foo
    base-path: /foo
    default-auth: header
    endpoints:
      foo:
        http: GET /foo
        args:
          arg:
            type: string
            param-type: query
        returns: Foo

And then update it to look like this (introducing a new optional query param newArg):

services:
  FooService:
    name: Foo Service
    package: com.palantir.foo
    base-path: /foo
    default-auth: header
    endpoints:
      foo:
        http: GET /foo
        args:
          arg:
            type: string
            param-type: query
          newArg:
            type: optional<string>
            param-type: query
        returns: Foo

Then FooService will generated with a method like this:

@Deprecated
default Foo foo(AuthHeader authHeader, String arg) {
    return foo(authHeader, arg, Optional.empty());
}

Which means that clients using FooService can upgrade their dependency without incurring any dev breaks. FooServiceBlocking however doesn't generate those methods, which makes releasing wire-safe API changes trigger dev breaks for FooServiceBlocking users.

What did you want to happen?

FooServiceBlocking should generate deprecated methods in order to avoid dev breaks. There's a similar argument to be made with FooServiceAsync.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the Java generator entry points for FooServiceBlocking and compare them with the existing FooService compatibility-method generation; also inspect the analogous FooServiceAsync path mentioned in the issue. Done means blocking and async services generate deprecated overloads when a new optional query parameter is introduced, preserving source compatibility for existing clients.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, backend-api-design
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.