Sttp client 4: improving the developer experience

Adrien Piquerez created a thorough and code-complete proposal on overhauling sttp client’s RequestT and SttpBackend types, by splitting them into multiple traits/classes, and thus reducing the number of type parameters. This is of course a binary-incompatible change, and would have to form the basis of sttp version 4.

Using that occasion, I’d like to gather wider feedback not only on the proposal, but also on your experiences with learning and using sttp client.

Starting with learning, some questions that would be helpful for us to understand how to improve the developer experience when using sttp:

  • what did you find most puzzling, when learning sttp?
  • when explaining sttp to co-workers, what was hardest for them to grasp?
  • which compiler messages have been misleading or not helpful?
  • do you use IDE’s type inference for sttp’s data structures, and if so, does it work well for you? did you understand why a specific type was inferred, and what the type means?
  • what was the largest road-block, that slowed you down when trying to make your first HTTP request using sttp?

Then, moving from learning to using sttp:

  • what’s are some of your daily “gotchas” that you have to keep in mind, when working with sttp?
  • is there any type of problem that surfaces again and again?
  • considering type safety: which area could be more type-safe, preventing some common bugs that need testing to detect?
  • how often do you define custom backend wrappers? do they work with a single, or multiple other backends / effect types / capabilities?
  • do you leverage sttp’s capability of customising any request (both partial & with the method/uri specified) using a single method?

Finally: if you have any idea on improving the API (even if it seems wild and improbable) - that’s the place to share :slight_smile:

Thank you!

1 Like
  • what did you find most puzzling, when learning sttp?

Websocket support, but this is (partially) gone from signatures now.

  • is there any type of problem that surfaces again and again?

response parsers (asJson). They are a bit complicated when you need to use anything more complicated. I cant give anything more precise at the moment but I remember fighting with them on couple occasions.

  • how often do you define custom backend wrappers? do they work with a single, or multiple other backends / effect types / capabilities?

We have some in many places, so relatively often. They typically need to work only with one underlying backend.

  • do you leverage sttp’s capability of customising any request (both partial & with the method/uri specified) using a single method?

you probably mean generic code that applies the same changes regardless of request completeness. If thats the case I can’t recall such code.

Finally: if you have any idea on improving the API (even if it seems wild and improbable) - that’s the place to share :slight_smile:

What I would love to have is ability to access raw response, regardless of what transformation where applied on top. Obviously this wont be possible for streams, but for most common case of strings/bytes being sent, this should be doable. We have an awkward asBoth() usage but we introduced some bugs when used not properly.

1 Like

if you have any idea on improving the API

Middlewares as first class Tapir concept.
Usecase: Distributed tracing middleware should be able to add the tracing headers to the docs.

Another thing I remember was challenging is to implement a monitoring http4s middleware that can figure out which endpoint is being hit so that it can increment the correct guage. It would be nice if Tapir Middleware would/could run after routing and has access to the endpoint object.

That’s a different project, but good suggestion as well - maybe you could move this to the tapir forum?

I’ll also change the title to explicitly say it’s about the client, my bad :slight_smile:

1 Like

Ditto - especially for dealing with broken APIs. e.g. reply with JSON on errors most of the time, but occasionally send back a raw string.

Ditto. We find it difficult to debug deserialization errors (especially with zio-json where error messages only show the offending next character).

what did you find most puzzling, when learning sttp?
The ZIO encoding with two separate error encodings. Most of the time absolve is fine, but new sttp users find this challenging.

considering type safety: which area could be more type-safe, preventing some common bugs that need testing to detect?

the uri interpolator is seductive, but can easily generate bad uri’s (e.g. substituting something besides strings)

Finally: if you have any idea on improving the API (even if it seems wild and improbable) - that’s the place to share :slight_smile:

  • We would like to see RequestMetadata included in ResponseException
1 Like