Redesign of the API client, including questioning its usefulness

[tloubrieu-jpl]

💡 Description

The value of the pds.api-client is questionable, we need to find a better solution for our users.

See slack thread:
Thomas G Loubrieu
16 hours ago
Overall the pds.api-client is maybe more a pain than it is helping compared to using requests . Maybe the only advantage is that is returns structured objects according to the API model but I am not sure if it is worth it. I will be interested in your opinion on that.
3 replies

Joseph C Jacob
14 hours ago
I think a Python wrapper around requests for a particular web service is a common abstraction and can be useful for end users if it is designed to be simple to use (maybe our api_client isn’t simple enough or just needs better documentation). Eliminating the pds.api-client Python API would have the upside of leaving fewer things to maintain and test. :astro-shrug:

Alex E Dunn
2 minutes ago
While it’s true that it’s common, I think the core question is “what value is added by wrapping it?”
Simplification of auth and pagination are common answers, or “the API is poorly-designed and common use-cases aren’t accounted for” but that’s not true here (I think?) and the better the API design is, the less room for adding value there is imho.
There’s also the argument that if someone can write enough Python to use the api client effectively, they can probably write a transparent iterator for pagination (for example).
Possibly a good middle-ground might be to offer a companion package to the API containing just the structured objects and related utils, rather than an API client, and ensure that your API is sensible and easy to use directly.Thomas G Loubrieu
16 hours ago
Overall the pds.api-client is maybe more a pain than it is helping compared to using requests . Maybe the only advantage is that is returns structured objects according to the API model but I am not sure if it is worth it. I will be interested in your opinion on that.
3 replies

Joseph C Jacob
14 hours ago
I think a Python wrapper around requests for a particular web service is a common abstraction and can be useful for end users if it is designed to be simple to use (maybe our api_client isn’t simple enough or just needs better documentation). Eliminating the pds.api-client Python API would have the upside of leaving fewer things to maintain and test. :astro-shrug:

Alex E Dunn
2 minutes ago
While it’s true that it’s common, I think the core question is “what value is added by wrapping it?”
Simplification of auth and pagination are common answers, or “the API is poorly-designed and common use-cases aren’t accounted for” but that’s not true here (I think?) and the better the API design is, the less room for adding value there is imho.
There’s also the argument that if someone can write enough Python to use the api client effectively, they can probably write a transparent iterator for pagination (for example).
Possibly a good middle-ground might be to offer a companion package to the API containing just the structured objects and related utils, rather than an API client, and ensure that your API is sensible and easy to use directly.Thomas G Loubrieu
16 hours ago
Overall the pds.api-client is maybe more a pain than it is helping compared to using requests . Maybe the only advantage is that is returns structured objects according to the API model but I am not sure if it is worth it. I will be interested in your opinion on that.
3 replies

Joseph C Jacob
14 hours ago
I think a Python wrapper around requests for a particular web service is a common abstraction and can be useful for end users if it is designed to be simple to use (maybe our api_client isn’t simple enough or just needs better documentation). Eliminating the pds.api-client Python API would have the upside of leaving fewer things to maintain and test. :astro-shrug:

Alex E Dunn
2 minutes ago
While it’s true that it’s common, I think the core question is “what value is added by wrapping it?”
Simplification of auth and pagination are common answers, or “the API is poorly-designed and common use-cases aren’t accounted for” but that’s not true here (I think?) and the better the API design is, the less room for adding value there is imho.
There’s also the argument that if someone can write enough Python to use the api client effectively, they can probably write a transparent iterator for pagination (for example).
Possibly a good middle-ground might be to offer a companion package to the API containing just the structured objects and related utils, rather than an API client, and ensure that your API is sensible and easy to use directly.